KML offre tre modi per aggiungere dati personalizzati a una funzionalità KML. L'approccio scelto dipende dal tipo di dati che aggiungi e da come prevedi di utilizzarli nella tua presentazione KML. In particolare, l'elemento <ExtendedData> fornisce i seguenti meccanismi:
- Elemento <Data>: consente di aggiungere coppie nome/valore non digitate ai dati utente associati a una determinata funzione (NetworkLink, Segnaposto, Overlay terra, Fotooverlay, Overlay schermo, Documento o Cartella). Per impostazione predefinita, queste coppie vengono visualizzate nel fumetto. Queste informazioni possono essere utilizzate anche per la sostituzione delle entità nell'elemento <text> di <BalloonStyle>. Consulta la sezione relativa all'utilizzo dell'elemento BalloonStyle come modello.
- Gli elementi <Schema> e <SchemaData> consentono di aggiungere dati digitati ai dati utente associati a una determinata funzionalità.
- Dati XML arbitrari: consentono di conservare i dati utente all'interno di un file KML. Google Earth trasmette questi dati insieme al file e li salva, ma non li utilizza.
Nota: questi tre meccanismi possono essere combinati nello stesso file. Se aggiungi tipi di dati diversi da fonti diverse, potrebbe essere opportuno utilizzare l'approccio basato sui dati digitati (Schema/SchemaData) per alcuni dati personalizzati e utilizzare i dati non digitati (Dati) per altri dati personalizzati.
Quale approccio dovresti usare?
Nella maggior parte dei casi, l'elemento <Data> offre il meccanismo più semplice ed efficace per aggiungere dati non digitati a una funzionalità KML. Questo metodo è relativamente facile da implementare e offre il vantaggio di facilitare l'utilizzo di un modello BalloonStyle, che può essere applicato a tutti i segnaposto di un file KML. Per un esempio di questo utilizzo, consulta Sostituzione di entità per elementi di dati estesi.
Gli elementi <Schema> e <SchemaData> consentono di aggiungere dati utente digitati. Questi elementi vengono offerti principalmente agli utenti con dati GIS (Geographic Information System). Se hai dati digitati e utilizzati da un'applicazione di computer esterna, probabilmente dovrai usare gli elementi <Schema> e <SchemaData> per aggiungere tipi di dati strutturati a una funzionalità. (Google Earth non utilizza queste informazioni digitate, ma l'altra applicazione potrebbe richiederle). Gli utenti occasionali probabilmente non hanno bisogno degli aspetti più tecnici offerti da questo meccanismo. Come <Data>, <SchemaData> facilita l'utilizzo dei modelli per BalloonStyle.
Se devi semplicemente trasmettere dati insieme a un file KML e non hai bisogno di Google Earth per elaborare i dati, utilizza la funzionalità dei dati XML arbitrari, che ti consente di fare riferimento a un prefisso dello spazio dei nomi XML e di trasmettere i dati nel contesto KML corrente. Per saperne di più, consulta la sezione Dati XML arbitrari.
Aggiunta di coppie di tipi/nome non digitate
L'elemento <Data> è un meccanismo semplice ma potente per aggiungere coppie di tipo/valore non digitate a una funzionalità KML. La sintassi per questo elemento è la seguente:
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
L'attributo name è un ID univoco per questa parte dei dati. L'elemento <displayName> viene utilizzato quando vuoi visualizzare il nome di questi dati in un formato semplice da usare. <displayName> può contenere CDATA che include spazi, URL e link ipertestuali.
Di seguito è riportato un esempio di segnaposto che contiene dati personalizzati su diverse buche di un campo da golf:
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>My Golf Course Example</name>
<Placemark>
<name>Club house</name>
<ExtendedData>
<Data name="holeNumber">
<value>1</value>
</Data>
<Data name="holeYardage">
<value>234</value>
</Data>
<Data name="holePar">
<value>4</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.956,33.5043</coordinates>
</Point>
</Placemark>
<Placemark>
<name>By the lake</name>
<ExtendedData>
<Data name="holeNumber">
<value>5</value>
</Data>
<Data name="holeYardage">
<value>523</value>
</Data>
<Data name="holePar">
<value>5</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.95,33.5024</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Questa schermata mostra come, per impostazione predefinita, vengono visualizzati gli elementi <Dati> in una tabella nel fumetto del segnaposto:
Esempio di dati che utilizza gli stili predefiniti per il fumetto
Recensione: utilizzando l'elemento BalloonStyle come modello
In KML puoi definire uno stile una volta e assegnargli un ID. Dopo aver definito lo stile in questo modo, puoi farvi riferimento più volte all'interno del file KML (o all'interno di altri file KML) utilizzando l'elemento <styleUrl>. Uno stile definito in questo modo è definito stile condiviso. L'elemento <text> all'interno di <BalloonStyle> supporta la sostituzione delle entità. I singoli valori possono essere sostituiti per ogni istanza dell'entità. Le entità standard che possono essere sostituite sono le seguenti:
- $[nome]
- Sostituito dal nome del segnaposto
- $[descrizione]
- Sostituito dalla descrizione del segnaposto
- $[indirizzo]
- Sostituito con l'indirizzo del segnaposto
- $[id]
- Sostituito con l'ID del segnaposto
- $[Snippet]
- Sostituito dallo snippet del segnaposto
- $[geDirections]
- Sostituito dalle indicazioni stradali A/D del segnaposto
Sostituzione di entità per elementi di dati estesi
Google Earth supporta anche la sostituzione di determinati elementi di dati estesi nell'elemento <text> di <BalloonStyle>. Nell'elemento <text> puoi fare riferimento alle seguenti entità:
| Variabile | Sostituito con | Esempio |
|---|---|---|
| $[name_attribute_of_Data_element] | Contenuto dell'elemento <value> | bucoNumero, bucoYardage |
| $[nome_attributo_dei_dati/Nome visualizzato] | Contenuto dell'elemento <displayName> | Numero di buchi, giardino dei fori |
Di seguito è riportato un esempio che crea un modello <BalloonStyle> per il campo da golf. Per ogni fumetto del segnaposto, Google Earth sostituisce il nome del segnaposto e poi scrive le informazioni contenenti il numero del buco, il par e la yardage di ogni singolo buco:
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>Data+BalloonStyle</name>
<Style id="golf-balloon-style">
<BalloonStyle>
<text>
<![CDATA[
This is $[name]
This is hole $[holeNumber]
The par for this hole is $[holePar]
The yardage is $[holeYardage]
]]>
</text>
</BalloonStyle>
</Style>
<!-- Shared style sample
Two Placemarks use the same balloon template
-->
<Placemark>
<name>Club house</name>
<styleUrl>#golf-balloon-style</styleUrl>
<ExtendedData>
<Data name="holeNumber">
<value>1</value>
</Data>
<Data name="holeYardage">
<value>234</value>
</Data>
<Data name="holePar">
<value>4</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.956,33.5043</coordinates>
</Point>
</Placemark>
<Placemark>
<name>By the lake</name>
<styleUrl>#golf-balloon-style</styleUrl>
<ExtendedData>
<Data name="holeNumber">
<value>5</value>
</Data>
<Data name="holeYardage">
<value>523</value>
</Data>
<Data name="holePar">
<value>5</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.95,33.5024</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Ecco un'acquisizione schermo di questo esempio:
Esempio di dati che utilizza gli stili predefiniti per il fumetto
Ecco un esempio più realistico dell'utilizzo dell'elemento <displayName>. Questa tecnica si presta alla localizzazione del testo e a una formattazione più elaborata.
<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>Entity-Replacement</name>
<Style id="displayName-value">
<BalloonStyle>
<text>
<![CDATA[
This is $[name]<br/>
$[holeNumber/displayName] $[holeNumber]<br/>
$[holePar/displayName] $[holePar]<br/>
$[holeYardage/displayName] $[holeYardage]
]]>
</text>
</BalloonStyle>
</Style>
<!-- Shared style sample
Two Placemarks use the same balloon template
-->
<Placemark>
<name>Club house</name>
<styleUrl>#displayName-value</styleUrl>
<ExtendedData>
<Data name="holeNumber">
<displayName><![CDATA[
<b>This is hole </b>
]]></displayName>
<value>1</value>
</Data>
<Data name="holePar">
<displayName><![CDATA[
<i>The par for this hole is </i>
]]></displayName>
<value>4</value>
</Data>
<Data name="holeYardage">
<displayName><![CDATA[
<b><i>The yardage is </i></b>
]]></displayName>
<value>234</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.956,33.5043</coordinates>
</Point>
</Placemark>
<Placemark>
<name>By the lake</name>
<styleUrl>#Entity-Replacement</styleUrl>
<ExtendedData>
<Data name="holeNumber">
<displayName><![CDATA[
<b>This is hole </b>
]]></displayName>
<value>5</value>
</Data>
<Data name="holePar">
<displayName><![CDATA[
<i>The par for this hole is </i>
]]></displayName>
<value>5</value>
</Data>
<Data name="holeYardage">
<displayName><![CDATA[
<b><i>The yardage is </i></b>
]]></displayName>
<value>523</value>
</Data>
</ExtendedData>
<Point>
<coordinates>-111.95,33.5024</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Di seguito è riportato un esempio di fumetto che utilizza il seguente modello:
Aggiungere dati digitati a una funzionalità
Gli elementi <Schema> e <SchemaData> consentono di aggiungere dati digitati a una funzionalità. Alcune applicazioni GIS e di programmazione richiedono questa funzionalità perché trattano dati digitati.
Panoramica dell'aggiunta di dati digitati
Per aggiungere un tipo personalizzato a una funzionalità KML, devi eseguire due attività di base:
- Crea l'elemento <Schema>, che dichiara il nuovo tipo.
- Crea istanze del nuovo tipo utilizzando l'elemento <SchemaData>.
Dichiarare l'elemento schema
L'elemento Schema dichiara un tipo strutturato. <Schema> è sempre un elemento secondario di <Documento>. Un documento può contenere zero o più elementi dello schema.
L'attributo id
L'elemento <Schema> ha sempre un attributo ID, mentre viene fatto riferimento a quando vengono create istanze di questo tipo (utilizzando <SchemaData>). Questo ID deve essere univoco all'interno del file KML.
Il nome dell'attributo
L'attributo name, utilizzato per la sostituzione dell'entità, è facoltativo.
Sintassi
La sintassi dell'elemento schema è la seguente:
<Schema name="string" id="ID">
<SimpleField type="string" name="string">
<displayName>...</displayName> <!-- string -->
</SimpleField>
</Schema>
Un campo <SimpleField> ha sempre gli attributi name e type. Se non contiene entrambi gli attributi, il campo viene ignorato. L'attributo name viene utilizzato per la sostituzione di entità nell'elemento <text> di <BalloonStyle>. Il tipo di Simplefield può essere uno dei seguenti:
stringintuintshortushortfloatdoublebool
Definisci ogni istanza dei dati
Utilizza l'elemento <SchemaData> per creare un'istanza del tipo definito dall'utente. La sintassi di <SchemaData> è la seguente:
<ExtendedData>
<SchemaData schemaUrl="anyURI">
<SimpleData name=""> ... </SimpleData> <!-- string -->
</SchemaData>
</ExtendedData>
L'attributo schemaUrl fa riferimento all'id dello schema che dichiara il tipo (proprio come uno styleUrl fa riferimento all'id di uno Style già dichiarato).Se schemaUrl è un indirizzo http, Google Earth recupera questo file dalla rete. Può esserci una sola istanza di un certo tipo definito dall'utente per segnaposto.
Esempio
L'esempio seguente dichiara un tipo definito dall'utente denominato ScenicVista. Questo tipo contiene tre campi: TrailHeadName, TrailLength ed ElevationIncrease. Il campo TrailHeadName contiene valori di tipo string. Il campo TrailLength contiene valori di tipo double. Il campo ElevationIncrease contiene valori di tipo int. Il segnaposto Percorso facile contiene un'istanza di questo tipo di utente. Questa istanza ha un valore "Pi nel cielo" per il campo TrailHeadName, un valore pari a 3, 14159 per il campo TrailLength e un valore 10 per il campo ElevationIncrease.
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>ExtendedData+SchemaData</name>
<open>1</open>
<!-- Declare the type "TrailHeadType" with 3 fields -->
<Schema name="TrailHeadType" id="TrailHeadTypeId">
<SimpleField type="string" name="TrailHeadName">
<displayName><![CDATA[<b>Trail Head Name</b>]]></displayName>
</SimpleField>
<SimpleField type="double" name="TrailLength">
<displayName><![CDATA[<i>Length in miles</i>]]></displayName>
</SimpleField>
<SimpleField type="int" name="ElevationGain">
<displayName><![CDATA[<i>Change in altitude</i>]]></displayName>
</SimpleField>
</Schema>
<!-- This is analogous to adding three fields to a new element of type TrailHead:
<TrailHeadType>
<TrailHeadName>...</TrailHeadName>
<TrailLength>...</TrailLength>
<ElevationGain>...</ElevationGain>
</TrailHeadType>
-->
<!-- Instantiate some Placemarks extended with TrailHeadType fields -->
<Placemark>
<name>Easy trail</name>
<ExtendedData>
<SchemaData schemaUrl="#TrailHeadTypeId">
<SimpleData name="TrailHeadName">Pi in the sky</SimpleData>
<SimpleData name="TrailLength">3.14159</SimpleData>
<SimpleData name="ElevationGain">10</SimpleData>
</SchemaData>
</ExtendedData>
<Point>
<coordinates>-122.000,37.002</coordinates>
</Point>
</Placemark>
<Placemark>
<name>Difficult trail</name>
<ExtendedData>
<SchemaData schemaUrl="#TrailHeadTypeId">
<SimpleData name="TrailHeadName">Mount Everest</SimpleData>
<SimpleData name="TrailLength">347.45</SimpleData>
<SimpleData name="ElevationGain">10000</SimpleData>
</SchemaData>
</ExtendedData>
<Point>
<coordinates>-121.998,37.0078</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Esempio di schemaData che utilizza lo stile predefinito per il fumetto
Sostituzione entità per displayName
Il meccanismo di schema/schemaData supporta anche la sostituzione delle entità nell'elemento <text> dell'elemento <BalloonStyle>.
L'elemento <displayName> di <Schema> ti consente di fornire una versione facile da usare per un tipo di dati personalizzato. La modifica della stringa in <Schema> ha l'effetto di cambiare il valore di <displayName> per tutte le caratteristiche che contengono quel tipo.
Nell'elemento <text> dell'elemento <BalloonStyle>, utilizza la seguente sintassi per qualificare <displayName>:
$[TYPENAME/TYPEFIELD/displayName]
dove
- TIPO
- è l'attributo nome di <Schema>
- CAMPO TIPO
- è l'attributo nome di <SimpleField>
- displayName
- è l'elemento <displayName> in <SimpleField>
Nel codice riportato di seguito viene aggiunto un modello BalloonStyle all'esempio di schemaData precedente. Come nell'esempio del campo da golf, il modello viene creato utilizzando gli elementi <Style>, <BalloonStyle> e <text> all'inizio del documento. Ogni segnaposto nel file fa riferimento a questo modello di stile (denominato "ExtendedData+SchemaData").
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>ExtendedData+SchemaData</name>
<open>1</open>
<!-- Create a balloon template referring to the user-defined type -->
<Style id="trailhead-balloon-template">
<BalloonStyle>
<text>
<![CDATA[
<h2>My favorite trails!</h2>
<br/><br/>
The $[TrailHeadType/TrailHeadName/displayName] is <i>$[TrailHeadType/TrailHeadName]</i>.
The trail is $[TrailHeadType/TrailLength] miles. <br/>
The climb is $[TrailHeadType/ElevationGain] meters. <br/><br/>
]]>
</text>
</BalloonStyle>
</Style>
<!-- Declare the type "TrailHeadType" with 3 fields -->
<Schema name="TrailHeadType" id="TrailHeadTypeId">
<SimpleField type="string" name="TrailHeadName">
<displayName><![CDATA[<b>Trail Head Name</b>]]></displayName>
</SimpleField>
<SimpleField type="double" name="TrailLength">
<displayName><![CDATA[<i>The length in miles</i>]]></displayName>
</SimpleField>
<SimpleField type="int" name="ElevationGain">
<displayName><![CDATA[<i>change in altitude</i>]]></displayName>
</SimpleField>
</Schema>
<!-- Instantiate some Placemarks extended with TrailHeadType fields -->
<Placemark>
<name>Easy trail</name>
<styleUrl>#trailhead-balloon-template</styleUrl>
<ExtendedData>
<SchemaData schemaUrl="#TrailHeadTypeId">
<SimpleData name="TrailHeadName">Pi in the sky</SimpleData>
<SimpleData name="TrailLength">3.14159</SimpleData>
<SimpleData name="ElevationGain">10</SimpleData>
</SchemaData>
</ExtendedData>
<Point>
<coordinates>-122.000,37.002</coordinates>
</Point>
</Placemark>
<Placemark>
<name>Difficult trail</name>
<styleUrl>#trailhead-balloon-template</styleUrl>
<ExtendedData>
<SchemaData schemaUrl="#TrailHeadTypeId">
<SimpleData name="TrailHeadName">Mount Everest</SimpleData>
<SimpleData name="TrailLength">347.45</SimpleData>
<SimpleData name="ElevationGain">10000</SimpleData>
</SchemaData>
</ExtendedData>
<Point>
<coordinates>-121.998,37.0078</coordinates>
</Point>
</Placemark>
</Document>
</kml>
Esempio di schemaData che utilizza un modello BalloonStyle
Confronta i fumetti creati con un modello BalloonStyle con quelli degli stessi dati visualizzati nell'acquisizione precedente dello schermo.
Aggiungere dati XML arbitrari a una funzionalità
Il modo più semplice per aggiungere dati utente a una funzionalità è aggiungere i dati direttamente come valore di <ExtendedData>. Google Earth conserva questi dati, ma non li elabora.
Gli elementi di dati personalizzati aggiunti in questo modo devono includere un nome di prefisso (xmlns:prefix="namespace"). Questo prefisso può essere aggiunto all'elemento <kb> o all'elemento <ExtendedData>. Il prefisso dello spazio dei nomi esterno deve qualificare ogni istanza dei dati utente, come mostrato nell'esempio seguente:
<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
<name>ExtendedData Test</name>
<Placemark>
<name>CampsiteData</name>
<!-- Imported schema requires use of namespace prefix -->
<ExtendedData xmlns:camp="http://campsites.com">
<camp:number>14</camp:number>
<camp:parkingSpaces>2</camp:parkingSpaces>
<camp:tentSites>4</camp:tentSites>
</ExtendedData>
<Point>
<coordinates>-114.041,53.7199</coordinates>
</Point>
</Placemark>
</Document>
</kml>