KML bietet drei Möglichkeiten, um einem KML-Element benutzerdefinierte Daten hinzuzufügen. Welchen Ansatz Sie wählen, hängt davon ab, welche Art von Daten Sie hinzufügen und wie Sie die Daten in Ihrer KML-Präsentation verwenden möchten. Das <ExtendedData>-Element bietet folgende Mechanismen:
- <Data>-Element: Damit können Sie den Nutzerdaten, die einer bestimmten Funktion (Netzwerk-Link, Ortsmarkierung, Boden-Overlay, Foto-Overlay, Bildschirm-Overlay, Dokument oder Ordner) zugeordnet sind, untypische Name/Wert-Paare hinzufügen. Diese Name/Wert-Paare werden standardmäßig im Info-Pop-up angezeigt. Diese Informationen können auch für das Ersetzen von Elementen im <text>-Element von <BalloonStyle> verwendet werden. Weitere Informationen finden Sie im Abschnitt BalloonStyle-Element als Vorlage verwenden.
- <Schema>- und <SchemaData>-Elemente: Hiermit können Sie den Nutzerdaten, die mit einer bestimmten Funktion verknüpft sind, typisierte Daten hinzufügen.
- Beliebige XML-Daten: Hiermit können Sie Nutzerdaten in einer KML-Datei beibehalten. Google Earth übergibt diese Daten zusammen mit der Datei und speichert sie, verwendet sie aber nicht.
Hinweis:Diese drei Mechanismen können in derselben Datei kombiniert werden. Wenn Sie verschiedene Datentypen aus verschiedenen Quellen hinzufügen, ist es unter Umständen sinnvoll, für einige benutzerdefinierte Daten den Ansatz mit typisierten Daten (Schema/SchemaData) und für andere benutzerdefinierte Daten (nicht typisierte Daten) zu verwenden.
Welchen Ansatz sollten Sie wählen?
In den meisten Fällen bietet das <Data>-Element die einfachste und wirksamste Methode zum Hinzufügen von nicht typisierten Daten in KML-Elemente. Diese Methode ist relativ einfach zu implementieren und bietet den Vorteil, dass sie eine BalloonStyle-Vorlage verwenden, die auf alle Ortsmarken in einer KML-Datei angewendet werden kann. Ein Beispiel hierfür finden Sie unter Entitätsersetzung für erweiterte Datenelemente.
Mit den Elementen <Schema> und <SchemaData> können Sie typisierte Nutzerdaten hinzufügen. Diese Elemente werden hauptsächlich für Nutzer mit GIS-Daten (Geographic Information System) angeboten. Wenn Sie Daten eingegeben haben, die von einer externen Computeranwendung verwendet werden, müssen Sie wahrscheinlich die Elemente <Schema> und <SchemaData> verwenden, um einem Feature strukturierte Datentypen hinzuzufügen. (Diese Daten werden von Google Earth nicht verwendet, sind jedoch möglicherweise in Ihrer anderen Anwendung erforderlich.) Für gelegentliche Nutzer sind wahrscheinlich weniger technische Aspekte dieses Mechanismus erforderlich. Wie <Data> vereinfacht auch <SchemaData> die Verwendung von Vorlagen für BalloonStyle.
Wenn Sie einfach Daten zusammen mit einer KML-Datei übergeben möchten und Google Earth die Daten nicht verarbeiten muss, können Sie die Funktion für beliebige XML-Daten verwenden, mit der Sie auf ein XML-Namespace-Präfix verweisen und die Daten im aktuellen KML-Kontext übergeben können. Weitere Informationen finden Sie im Abschnitt Beliebige XML-Daten.
Hinzufügen von Name/Wert-Paaren ohne Typ
Das Element <Data> ist ein einfacher, aber leistungsstarker Mechanismus zum Hinzufügen von nicht typisierten Name/Wert-Paaren zu einem KML-Element. Die Syntax für dieses Element sieht so aus:
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
Das Attribut name ist eine eindeutige ID für diese Daten. Mit dem Element <displayName> wird der Name dieser Daten nutzerfreundlich dargestellt. <displayName> kann CDATA-Elemente mit Leerzeichen, URLs und Hyperlinks enthalten.
Hier sehen Sie ein Beispiel für eine Ortsmarkierung, die benutzerdefinierte Daten zu mehreren Löchern auf einem Golfplatz enthält:
<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>
Auf diesem Screenshot sehen Sie, wie die Elemente <Data> standardmäßig in einer Tabelle im Info-Pop-up der Ortsmarkierung angezeigt werden:
Datenbeispiel mit Standardstil für Info-Pop-up
Zusammenfassung: BalloonStyle-Element als Vorlage verwenden
In KML können Sie einen Stil einmal definieren und ihm eine ID zuweisen. Nachdem Sie den Stil so definiert haben, können Sie in der KML-Datei (oder in anderen KML-Dateien) mit dem <styleUrl>-Element mehrmals darauf verweisen. Ein so definierter Stil wird als gemeinsamer Stil bezeichnet. Das <text>-Element in <BalloonStyle> unterstützt die Entitätsersetzung. Für jede Instanz der Entität können einzelne Werte ersetzt werden. Folgende Standardentitäten können ersetzt werden:
- $[Name]
- Ersetzt durch den Namen der Ortsmarkierung
- [Beschreibung] $
- Ersetzt durch die Beschreibung der Ortsmarkierung
- $[Adresse]
- Ersetzt durch die Adresse der Ortsmarkierung
- [id] $
- Ersetzt durch die ID der Ortsmarkierung
- [Snippet]
- Ersetzt durch das Snippet der Ortsmarkierung
- $[geDirections]
- Ersetzt durch die Routenbeschreibung der Ortsmarkierung zu/von
Entitätsersetzung für erweiterte Datenelemente
Google Earth unterstützt außerdem die Entitätsersetzung bestimmter erweiterter Datenelemente innerhalb des <text>-Elements von <BalloonStyle>. Folgende Elemente können im <text>-Element referenziert werden:
| Variable | Ersetzt durch | Beispiel |
|---|---|---|
| $[name_Attribut_des_Datenelements] | Inhalt des <value>-Elements | holeNumber, LochYardage |
| $[name_attribut_von_Daten/displayName] | Inhalt des <displayName>-Elements | Lochnummer, Loch-Yard |
In diesem Beispiel wird eine <BalloonStyle>-Vorlage für den Golfplatz erstellt. Für jedes Info-Pop-up ersetzt Google Earth den Namen der Ortsmarkierung und schreibt dann Informationen über die Anzahl, das Par und die Grenzzahl jedes einzelnen Lochs:
<?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>
Hier ein Screenshot dieses Beispiels:
Datenbeispiel mit Standardstil für Info-Pop-up
Hier sehen Sie ein realistischeres Beispiel für die Verwendung des Elements <displayName>. Dieses Verfahren eignet sich zur Lokalisierung des Textes und für eine komplexere Formatierung.
<?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>
Hier ein Beispiel für ein Info-Pop-up mit dieser Vorlage:
Eingetippte Daten einem Element hinzufügen
Mit den Elementen <Schema> und <SchemaData> können Sie einem Element typisierte Daten hinzufügen. Bestimmte GIS- und Programmieranwendungen benötigen diese Funktion, da sie mit typisierten Daten arbeiten.
Eingegebene Daten hinzufügen
Zum Hinzufügen eines benutzerdefinierten Typs zu einem KML-Element führen Sie zwei grundlegende Aufgaben aus:
- Erstellen Sie das Element <Schema>, das Ihren neuen Typ deklariert.
- Erstellen Sie mit dem <SchemaData>-Element Instanzen des neuen Typs.
Schemaelement deklarieren
Das Schema-Element deklariert einen strukturierten Typ. <Schema> ist immer <Document> untergeordnet. Ein Dokument kann null oder mehr Schemaelemente enthalten.
Das ID-Attribut
Das <Schema>-Element hat immer ein ID-Attribut. Es wird auf Whish verwiesen, wenn Instanzen dieses Typs mit <SchemaData> erstellt werden. Diese ID muss innerhalb der KML-Datei eindeutig sein.
Das Attribut „Name“
Das Attribut name, das für das Ersetzen von Entitäten verwendet wird, ist optional.
Syntax
Das Schema-Element hat die folgende Syntax:
<Schema name="string" id="ID">
<SimpleField type="string" name="string">
<displayName>...</displayName> <!-- string -->
</SimpleField>
</Schema>
Ein <SimpleField>-Element hat immer die Attribute name und type. Wenn nicht beide Attribute vorhanden sind, wird das Feld ignoriert. Das Namensattribut wird für die Entitätsersetzung im <text>-Element von <BalloonStyle> verwendet. Ein Simplefield-Typ kann einer der folgenden sein:
stringintuintshortushortfloatdoublebool
Jede Instanz der Daten definieren
Verwenden Sie das Element <SchemaData>, um eine Instanz des benutzerdefinierten Typs zu erstellen. Die Syntax für <SchemaData> sieht so aus:
<ExtendedData>
<SchemaData schemaUrl="anyURI">
<SimpleData name=""> ... </SimpleData> <!-- string -->
</SchemaData>
</ExtendedData>
Das schemaUrl-Attribut verweist auf die id des Schemas, das den Typ angibt. Das gilt auch, wenn eine styleUrl auf die id eines Style-Elements verweist, das bereits deklariert ist. Wenn schemaUrl eine http-Adresse ist, ruft Google Earth diese Datei im gesamten Netzwerk ab. Pro Ortsmarkierung kann es nur eine Instanz eines benutzerdefinierten Typs geben.
Beispiel
Im folgenden Beispiel wird ein benutzerdefinierter Typ namens ScenicVista deklariert. Dieser Typ enthält drei Felder: TrailHeadName, TrailLength und ElevationGain. Das Feld TrailHeadName enthält Werte vom Typ string. Das Feld TrailLengt enthält Werte vom Typ double. Das Feld ElevationGain enthält Werte vom Typ int. Die Ortsmarkierung Easy Trail enthält eine Instanz dieses Nutzertyps. Diese Instanz hat den Wert „Pi in the sky“ für das Feld TrailHeadName, einen Wert von 3, 14159 für das Feld TrailLength und einen Wert von 10 für das Feld ElevationGain.
<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>
SchemaData-Beispiel mit Standardstil für das Info-Pop-up
Entitätsersetzung für displayName
Der Mechanismus von Schema/SchemaData unterstützt auch das Ersetzen von Entitäten im <text>-Element des <BalloonStyle>-Elements.
Mit <displayName> von <Schema> können Sie eine benutzerfreundliche Version für einen benutzerdefinierten Datentyp angeben. Wenn Sie die Zeichenfolge einmal in <Schema> ändern, hat dies Auswirkungen auf die Änderung von <displayName> für alle Elemente, die diesen Typ enthalten.
Verwende im <text>-Element des <BalloonStyle>-Elements die folgende Syntax, um <displayName> zu qualifizieren:
$[TYPENAME/TYPEFIELD/displayName]
wobei
- TYPENAME
- ist das Attribut name von <Schema>.
- TYP
- ist das Attribut name von <SimpleField>
- displayName
- ist das Element <displayName> in <SimpleField>
Mit dem folgenden Code wird eine BalloonStyle-Vorlage zum vorherigen SchemaData-Beispiel hinzugefügt. Wie im Golf Course-Beispiel wird die Vorlage mit den Elementen <Style>, <BalloonStyle> und <text> am Anfang des Dokuments erstellt. Jede Ortsmarkierung in der Datei verweist auf diese Stilvorlage (namens "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>
SchemaData-Beispiel mit einer BalloonStyle-Vorlage
Info-Pop-up, das mit einer BalloonStyle-Vorlage erstellt wurde, mit dem Standard-Info-Pop-up-Stil für dieselben Daten vergleichen, die in der vorherigen Bildschirmaufnahme zu sehen waren.
Beliebige XML-Daten zu einem Feature hinzufügen
Die einfachste Möglichkeit, Nutzerdaten zu einem Element hinzuzufügen, besteht darin, die Daten direkt als Wert von <ExtendedData> hinzuzufügen. Google Earth bewahrt diese Daten auf, verarbeitet sie jedoch nicht.
Benutzerdefinierte Datenelemente, die auf diese Weise hinzugefügt werden, müssen ein namespace-Präfix enthalten (xmlns:prefix="namespace). Dieses Präfix kann dem Element <KML> oder dem Element <ExtendedData> hinzugefügt werden. Das externe Namespace-Präfix muss jede Instanz von Nutzerdaten erfüllen, wie im folgenden Beispiel gezeigt:
<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>