KML ofrece tres formas de agregar datos personalizados a un elemento KML. El enfoque que elijas dependerá del tipo de datos que agregues y de cómo planees utilizarlos en tu presentación en formato KML. Específicamente, el elemento <ExtendedData> proporciona los siguientes mecanismos:
- <Data>: Permite agregar pares de nombre/valor sin tipo a los datos del usuario asociados con un elemento determinado (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document, o Folder). Estos pares de nombre/valor se muestran en la viñeta de forma predeterminada. Esta información también se puede usar para reemplazar la entidad en el elemento <text> de <BalloonStyle>. (Consulta la sección Cómo usar el elemento BalloonStyle como plantilla).
- Elementos <Schema> y <SchemaData>: Le permiten agregar datos escritos a los datos del usuario asociados con una función específica.
- Datos XML arbitrarios: Te permiten conservar los datos de los usuarios en un archivo KML. Google Earth transfiere estos datos junto con el archivo y los guarda, pero no los utiliza.
Nota: Estos tres mecanismos pueden combinarse en el mismo archivo. Si agrega diferentes tipos de datos desde diferentes fuentes, puede ser apropiado usar el enfoque de datos escritos (Schema/SchemaData) para algunos de los datos personalizados y usar datos sin tipo (Data) para otros datos personalizados.
¿Qué enfoque deberías usar?
En la mayoría de los casos, el elemento <Data> ofrece el mecanismo más simple y potente para agregar datos sin tipo a un elemento KML. Este método es relativamente fácil de implementar y ofrece la ventaja de facilitar el uso de una plantilla de BalloonStyle, que se puede aplicar a todas las marcas de posición en un archivo KML. (Consulta Reemplazo de entidades para elementos de datos extendidos para ver un ejemplo de este uso).
Los elementos <Schema> y <SchemaData> le permiten agregar datos de tipo type. Estos elementos se ofrecen principalmente para los usuarios con datos de GIS (sistema de información geográfica). Si has escrito datos que usa una aplicación informática externa, es probable que necesites usar los elementos <Schema> y <SchemaData> para agregar tipos de datos estructurados a un elemento. (Google Earth no usa esta información escrita, pero tu otra aplicación puede necesitarla). Es probable que los usuarios casuales no necesiten los aspectos más técnicos que ofrece este mecanismo. Al igual que <Data>, <SchemaData> facilita el uso de plantillas para BalloonStyle.
Si solo necesitas pasar datos junto con un archivo KML y no necesitas que Google Earth procese los datos, usa la función de datos XML arbitrarios, que te permite hacer referencia a un prefijo de espacio de nombres XML y pasar los datos en el contexto KML actual. Para obtener más información, consulta la sección sobre datos XML arbitrarios.
Cómo agregar pares de nombre/valor sin tipo
El elemento <Data> es un mecanismo simple pero poderoso para agregar pares de nombre/valor sin tipo a un elemento KML. La sintaxis de este elemento es la que se muestra a continuación:
<ExtendedData>
<Data name="string">
<displayName>...</displayName> <!-- string -->
<value>...</value> <!-- string -->
</Data> </ExtendedData>
El atributo name es un ID único para este dato. El elemento <displayName> se usa cuando quieres mostrar el nombre de estos datos en un formato fácil de usar. El elemento <displayName> puede contener CDATA, incluidos los espacios, las URL y los hipervínculos.
A continuación, se incluye un ejemplo de una marca de posición que contiene datos personalizados sobre varios orificios en un campo 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>
Esta captura de pantalla muestra cómo se muestran los elementos de <datos> de forma predeterminada en una tabla en el globo de la marca de posición:
Ejemplo de datos con diseño predeterminado para el globo
Revisión: Cómo usar el elemento BalloonStyle como plantilla
En KML, puedes definir un estilo una vez y asignarle un ID. Después de definir el estilo de esta manera, puedes hacer referencia a él varias veces dentro del archivo KML (o de otros archivos KML) mediante el elemento <styleUrl>. Un estilo definido de esta manera se conoce como un estilo compartido. El elemento <text> de <BalloonStyle> admite el reemplazo de entidades. Se pueden sustituir valores individuales para cada instancia de la entidad. Las entidades estándar que se pueden reemplazar son las siguientes:
- $[nombre]
- Reemplazado con el nombre de la marca de posición
- $[description]
- Se reemplazó por la descripción de la marca de posición.
- $[dirección]
- Se reemplazó por la dirección de la marca de posición.
- $[id]
- Reemplazado con el ID de la marca de posición
- $[Fragmento]
- Reemplazado con el Fragmento de la marca de posición
- $[geDirections]
- Se reemplazó por las rutas en auto de la marca de posición "Desde/hacia"
Reemplazo de entidades para elementos de datos extendidos
Google Earth también permite reemplazar entidades de ciertos elementos de datos extendidos dentro del elemento <text> de <BalloonStyle>. Se puede hacer referencia a las siguientes entidades dentro del elemento <text>:
| Variable | Reemplazado por | Ejemplo |
|---|---|---|
| $[nombre_atributo_de_elemento_de_datos] | Contenido del elemento <value> | número de hoyo, hoyoYardage |
| $[nombre_atributo_de_datos/displayName] | Contenido del elemento <displayName> | Número de orificio, Hole Yardage |
A continuación, se muestra un ejemplo que crea una plantilla de <BalloonStyle> para el ejemplo del campo de golf. Para cada globo de marca de posición, Google Earth sustituye el nombre de la marca de posición y luego escribe la información que contiene el número de agujero, el par y el yardaje para cada agujero individual:
<?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>
A continuación, se ofrece una captura de pantalla de este ejemplo:
Ejemplo de datos con diseño predeterminado para el globo
Aquí hay un ejemplo más realista de cómo se usaría el elemento <displayName>. Esta técnica se presta para la localización del texto y un formato más elaborado.
<?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>
A continuación, se muestra un ejemplo de un globo que utiliza esta plantilla de estilo de globo:
Cómo agregar datos escritos a un elemento
Los elementos <Schema> y <SchemaData> le permiten agregar datos escritos a un elemento. Algunas aplicaciones GIS y de programación requieren esta función porque se ocupan de los datos escritos.
Descripción general sobre cómo agregar datos escritos
Para agregar un tipo personalizado a un elemento KML, debes realizar dos tareas básicas:
- Cree el elemento <Schema>, que declara su nuevo tipo.
- Crea instancias del nuevo tipo con el elemento <SchemaData>.
Declara el elemento de esquema
El elemento Schema declara un tipo estructurado. <Schema> siempre es un elemento secundario de <Document>. Un documento puede contener cero o más elementos de esquema.
El atributo id [id]
El elemento <Schema> siempre tiene un atributo id [id], y se hace referencia a él cuando se crean las instancias de este tipo (mediante <SchemaData>). Este ID debe ser único dentro del archivo KML.
El atributo 'nombre' [name]
El atributo name [nombre], que se usa para el reemplazo de entidades, es opcional.
Sintaxis
El elemento Schema tiene la siguiente sintaxis:
<Schema name="string" id="ID">
<SimpleField type="string" name="string">
<displayName>...</displayName> <!-- string -->
</SimpleField>
</Schema>
Un <SimpleField> siempre tiene los atributos name y type. Si no tiene ambos atributos, se ignora el campo. El atributo name se usa para reemplazar la entidad en el elemento <text> de <BalloonStyle>. El tipo de Simplefield puede ser uno de los siguientes:
stringintuintshortushortfloatdoublebool
Define cada instancia de los datos
Usa el elemento <SchemaData> para crear una instancia del tipo definido por el usuario. La sintaxis de <SchemaData> es la siguiente:
<ExtendedData>
<SchemaData schemaUrl="anyURI">
<SimpleData name=""> ... </SimpleData> <!-- string -->
</SchemaData>
</ExtendedData>
El atributo schemaUrl hace referencia al id del esquema que declara el tipo (al igual que una styleUrl hace referencia al id de un Style que ya se declaró).Si schemaUrl es una dirección http, Google Earth recupera este archivo en la red. Solo puede haber una instancia de un tipo definido por el usuario por marca de posición.
Ejemplo
En el siguiente ejemplo, se declara un tipo definido por el usuario llamado ScenicVista. Este tipo contiene tres campos: TrailHeadName, TrailLength y ElevationGain. El campo TrailHeadName contiene valores de tipo string. El campo SendLengt contiene valores de tipo double. El campo ElevationGain contiene valores de tipo int. El marcador llamado Easy Trail contiene una instancia de este tipo de usuario. Esta instancia tiene un valor de "Pi en el cielo" para el campo TrailHeadName, un valor de 3.14159 para el campo TrailLength y un valor de 10 para el campo 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>
Ejemplo de SchemaData con un estilo predeterminado para el globo
Reemplazo de entidades para displayName
El mecanismo Schema/SchemaData también admite el reemplazo de entidades en el elemento <text> del elemento <BalloonStyle>.
La etiqueta <displayName> de <Schema> le permite proporcionar una versión fácil de usar para un tipo de datos personalizado. Si se cambia la string una vez en <Schema>, se modificará el elemento <displayName> de todos los elementos que contengan ese tipo.
En el elemento <text> del elemento <BalloonStyle>, usa la siguiente sintaxis para calificar el <displayName>:
$[TYPENAME/TYPEFIELD/displayName]
donde
- TYPENAME
- es el atributo name de <Schema>
- TYPEFIELD
- es el atributo name de <SimpleField> .
- displayName
- es el elemento <displayName> dentro de <SimpleField>
El siguiente código agrega una plantilla BalloonStyle al ejemplo anterior de SchemaData. Al igual que en el ejemplo del campo de golf, la plantilla se crea con los elementos <Style>, <BalloonStyle> y <text> al comienzo del documento. Cada marca de posición del archivo hace referencia a esta plantilla de estilo (llamada "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>
Ejemplo de schemaData con una plantilla de BalloonStyle
Compara el globo creado con una plantilla BalloonStyle con el estilo de globo predeterminado de los mismos datos que se muestran en la captura de pantalla anterior.
Cómo agregar datos XML arbitrarios a un elemento
La manera más sencilla de agregar datos de usuario a un elemento es agregar los datos directamente como un valor de <ExtendedData>. Google Earth conserva estos datos, pero no los procesa.
Los elementos de datos personalizados que se agregan de esta manera deben incluir un prefijo de espacio de nombres (xmlns:prefix="namespace"). Este prefijo se puede agregar al elemento <kml> o <ExtendedData>. El prefijo del espacio de nombres externo debe calificar cada instancia de los datos del usuario, como se muestra en el siguiente ejemplo:
<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>