Il existe trois façons d'ajouter des données personnalisées à un élément KML. L'approche que vous choisissez dépend du type de données que vous ajoutez et de la manière dont vous prévoyez d'utiliser les données dans votre présentation KML. Plus précisément, l'élément <ExtendedData> fournit les mécanismes suivants:
- <Data> - permet d'ajouter des paires nom/valeur non typées aux données utilisateur associées à un élément géographique donné (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document ou Folder). Ces paires nom/valeur sont affichées dans l'info-bulle par défaut. Ces informations peuvent également être utilisées pour le remplacement d'entités dans l'élément <text> de <BalloonStyle> (consultez la section Utiliser l'élément BalloonStyle comme modèle).
- Les éléments <Schema> et <SchemaData> vous permettent d'ajouter des données saisies aux données utilisateur associées à un élément géographique donné.
- Données XML arbitraires : permet de conserver les données utilisateur dans un fichier KML. Google Earth transmet ces données avec le fichier et l'enregistre, mais ne l'utilise pas.
Remarque : Ces trois mécanismes peuvent être combinés dans le même fichier. Si vous ajoutez différents types de données provenant de différentes sources, il peut être approprié d'utiliser l'approche de données typées (Schema/SchemaData) pour certaines données personnalisées et d'utiliser des données non typées (Data) pour d'autres.
Quelle approche devriez-vous utiliser ?
Dans la plupart des cas, l'élément <Data> offre le mécanisme le plus simple et le plus puissant pour ajouter des données non typées à un élément KML. Cette méthode est relativement simple à mettre en œuvre et présente l'avantage de faciliter l'utilisation d'un modèle BalloonStyle, qui peut être appliqué à tous les repères d'un fichier KML. (Voir Remplacement des entités pour les éléments de données étendus pour un exemple de cette utilisation.)
Les éléments <Schema> et <SchemaData> vous permettent d'ajouter des données utilisateur typed. Ces éléments sont principalement proposés aux utilisateurs disposant de données SIG. Si vous avez saisi des données qui sont utilisées par une application informatique externe, vous devrez probablement utiliser les éléments <Schema> et <SchemaData> pour ajouter des types de données structurées à une caractéristique. (Google Earth n'utilise pas ces informations saisies, mais votre autre application peut les exiger.) Les utilisateurs occasionnels n'auront probablement pas besoin des aspects plus techniques proposés par ce mécanisme. Tout comme <Data>, <SchemaData> facilite l'utilisation de modèles pour BalloonStyle.
Si vous devez simplement transmettre des données avec un fichier KML et que vous ne souhaitez pas que Google Earth les traite, utilisez la fonctionnalité arbitraire de données XML, qui vous permet de référencer un préfixe d'espace de noms XML et de transmettre les données dans le contexte KML actuel. Pour en savoir plus, consultez la section Données XML arbitraires.
Ajout de paires nom/valeur non typées
L'élément <Data> est un mécanisme simple mais puissant qui permet d'ajouter des paires nom/valeur non typées à un élément géographique KML. La syntaxe de cet élément est la suivante :
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
L'attribut name est un identifiant unique pour cette donnée. L'élément <displayName> est utilisé lorsque vous souhaitez afficher le nom de ces données sous une forme conviviale. L'élément <displayName> peut contenir un bloc CDATA incluant des espaces, des URL et des liens hypertexte.
Voici un exemple de repère contenant des données personnalisées sur plusieurs trous d'un parcours de 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>
Cette capture d'écran montre comment les éléments <Data> sont affichés par défaut dans un tableau de l'infobulle du repère:
Exemple de données utilisant le style par défaut pour l'infobulle
À propos de l'utilisation de l'élément BalloonStyle comme modèle
Dans KML, vous pouvez définir un style une seule fois et lui attribuer un identifiant. Une fois le style défini, vous pouvez le référencer plusieurs fois dans le fichier KML (ou dans d'autres fichiers KML) à l'aide de l'élément <styleUrl>. Un style défini de cette manière est appelé style partagé. L'élément <text> dans <BalloonStyle> est compatible avec le remplacement d'entité. Des valeurs individuelles peuvent être remplacées pour chaque instance de l'entité. Les entités standards pouvant être remplacées sont les suivantes:
- $[nom]
- Remplacée par le nom du repère .
- $[description]
- Remplacée par la description du repère
- $[adresse]
- Valeur de remplacement par l'adresse du repère
- $[id]
- Remplacé par l'ID du repère.
- $[Extrait]
- Remplacée par l'extrait du repère
- $[geDirections]
- Remplacée par l'itinéraire en voiture du repère à destination du repère.
Remplacement d'entités pour les éléments de données étendus
Google Earth permet également le remplacement d'entités de certains éléments de données étendus dans l'élément <text> de <BalloonStyle>. Les entités suivantes peuvent être référencées dans l'élément <text> :
| Variable | Remplacé par | Exemple |
|---|---|---|
| $[name_attribute_of_Data_element] | Contenu de l'élément <value> | holeNumber, holeYardage |
| $[nom_attribut_des_données/displayName] | Contenu de l'élément <displayName> | Numéro de trou, jardinage |
Voici un exemple qui crée un modèle <BalloonStyle> pour l'exemple de parcours de golf. Pour chaque infobulle de repère, Google Earth remplace le nom du repère, puis écrit les informations contenant le numéro de trou, le par et la distance pour chaque trou:
<?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>
Voici une capture d'écran de cet exemple:
Exemple de données utilisant le style par défaut pour l'infobulle
Voici un exemple plus réaliste de l'utilisation de l'élément <displayName> . Cette technique se prête à la localisation du texte et à une mise en forme plus élaborée.
<?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>
Voici un exemple d'infobulle utilisant ce modèle:
Ajouter des données typées à un élément géographique
Les éléments <Schema> et <SchemaData> vous permettent d'ajouter des données saisies à un élément géographique. Certaines applications SIG et de programmation requièrent cette fonctionnalité, car elles traitent des données saisies.
Présentation de l'ajout de données saisies
Pour ajouter un type personnalisé à un élément KML, vous devez effectuer deux tâches de base:
- Créez l'élément <Schema> qui déclare votre nouveau type.
- Créez des instances du nouveau type à l'aide de l'élément <SchemaData>.
Déclarer l'élément de schéma
L'élément de schéma déclare un type structuré. <Schema> est toujours un enfant de <Document>. Un document peut contenir zéro, un ou plusieurs éléments de schéma.
Attribut "id" [identifiant]
L'élément <Schema> possède toujours un attribut d'identifiant, qui est référencé lorsque des instances de ce type sont créées (à l'aide de <SchemaData>). Cet identifiant doit être unique dans le fichier KML.
Nom : attribut
L'attribut name, utilisé pour le remplacement d'une entité, est facultatif.
Syntaxe
La syntaxe de l'élément de schéma est la suivante:
<Schema name="string" id="ID">
<SimpleField type="string" name="string">
<displayName>...</displayName> <!-- string -->
</SimpleField>
</Schema>
Un élément <SimpleField> contient toujours les attributs name et type. S'il ne contient pas les deux attributs, le champ est ignoré. L'attribut name est utilisé pour remplacer une entité dans l'élément <text> de <BalloonStyle>. Le type d'un Simplefield peut être l'un des suivants:
stringintuintshortushortfloatdoublebool
Définir chaque instance des données
Utilisez l'élément <SchemaData> pour créer une instance du type défini par l'utilisateur. La syntaxe de <SchemaData> est la suivante:
<ExtendedData>
<SchemaData schemaUrl="anyURI">
<SimpleData name=""> ... </SimpleData> <!-- string -->
</SchemaData>
</ExtendedData>
L'attribut schemaUrl fait référence à l'id du schéma qui déclare le type (tout comme un styleUrl fait référence à l'id d'un Style déjà déclaré).Si schemaUrl est une adresse http, Google Earth récupère ce fichier sur le réseau. Il ne peut y avoir qu'une seule instance d'un type donné défini par l'utilisateur par repère.
Exemple
L'exemple suivant déclare un type défini par l'utilisateur nommé ScenicVista. Ce type contient trois champs: TrailHeadName, TrailLength et ElevationGain. Le champ TrailHeadName contient des valeurs de type string. Le champ TrailLengt contient des valeurs de type double. Le champ ElevationGain contient des valeurs de type int. Le repère intitulé Tracé facile contient une instance de ce type d'utilisateur. Cette instance a une valeur "Pi in the sky" pour son champ TrailHeadName, une valeur de 3.14159 pour son champ TrailLength et une valeur de 10 pour son champ 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>
Exemple de schéma de données utilisant le style par défaut pour l'infobulle
Remplacement d'entité pour displayName
Le mécanisme Schema/SchemaData est également compatible avec le remplacement d'entités dans l'élément <text> de l'élément <BalloonStyle>.
L'élément <displayName> de <Schema> vous permet de fournir une version conviviale d'un type de données personnalisé. La modification de la chaîne une fois dans le <Schema> a pour effet de modifier le <displayName> pour tous les éléments géographiques qui contiennent ce type.
Dans l'élément <text> de l'élément <BalloonStyle>, utilisez la syntaxe suivante pour qualifier <displayName> :
$[TYPENAME/TYPEFIELD/displayName]
Où :
- TYPENAME
- est l'attribut name de <Schema>
- TYPEFIELDFIELD
- est l'attribut name de <SimpleField>
- displayName
- est l'élément <displayName> dans <SimpleField>
Le code suivant ajoute un modèle BalloonStyle à l'exemple SchemaData précédent. Comme dans l'exemple du parcours de golf, le modèle est créé à l'aide des éléments <Style>, <BalloonStyle> et <text> au début du document. Chaque repère du fichier fait référence à ce modèle de style (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>
Exemple de schéma de données de modèle BalloonStyle
Comparez l'info-bulle créée à l'aide d'un modèle BalloonStyle au style d'infobulle par défaut pour les mêmes données que celles de la capture d'écran précédente.
Ajouter des données XML arbitraires à une caractéristique
Le moyen le plus simple d'ajouter des données utilisateur à un élément géographique est d'ajouter les données directement en tant que valeur de <ExtendedData>. Google Earth conserve ces données, mais ne les traite pas.
Les éléments de données personnalisés ajoutés de cette manière doivent inclure un préfixe namespace (xmlns:prefix="namespace"). Ce préfixe peut être ajouté à l'élément <kml> ou à <ExtendedData>. Le préfixe d'espace de noms externe doit qualifier chaque instance de données utilisateur, comme illustré dans l'exemple suivant:
<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>