Como adicionar dados personalizados

O KML oferece três formas de adicionar dados personalizados a um elemento KML. O método que você escolhe depende do tipo de dado que você está adicionando e de como planeja usar os dados em sua apresentação KML. Especificamente, o elemento <ExtendedData> fornece os seguintes mecanismos:

  • Elemento <Data> - permite adicionar pares de nome/valor não digitados aos dados de usuário associados a determinado elemento (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document ou Folder). Por padrão, esses pares de nome/valor são exibidos no balão. Essas informações também podem ser usadas para substituição de entidades no elemento <text> de <BalloonStyle>. (Consulte a seção Como usar o elemento BalloonStyle como um modelo.)
  • Elementos <Schema> e <SchemaData> - permitem adicionar dados digitados aos dados do usuário associados a determinado elemento.
  • Dados XML aleatórios - permitem preservar os dados do usuário em um arquivo KML. O Google Earth transmite esses dados junto com o arquivo e salva-os, mas não os usa.

Observação: esses três mecanismos podem ser combinados no mesmo arquivo. Se você estiver adicionando tipos diferentes de dados de fontes diferentes, talvez seja apropriado usar a abordagem de dados digitados (Schema/SchemaData) para alguns dos dados personalizados e usar dados não digitados (Data) para outros.

Qual abordagem deve ser usada?

Na maioria dos casos, o elemento <Data> oferece o mecanismo mais simples e poderoso de adicionar dados não digitados a um elemento KML. Esse método é relativamente fácil de implementar e oferece a vantagem de facilitar o uso de um modelo de BalloonStyle, que pode ser aplicado a todos os marcadores em um arquivo KML. (Consulte Substituição de entidades para elementos de dados estendidos para ver um exemplo deste uso.)

Os elementos <Schema> e <SchemaData> permitem adicionar dados de usuário digitados. Esses elementos são oferecidos principalmente para usuários com dados de GIS (Geographic Information System). Se você tiver dados digitados que sejam usados por um aplicativo de computador externo, provavelmente precisará usar os elementos <Schema> e <SchemaData> para adicionar tipos de dados estruturados a um elemento. O Google Earth não usa essas informações digitadas, mas seus outros aplicativos podem exigi-las. Provavelmente os usuários casuais não precisarão de aspectos mais técnicos oferecidos por esse mecanismo. Assim como <Data>, <SchemaData> facilita o uso de modelos para BalloonStyle.

Se você precisa somente transmitir dados junto com um arquivo KML e não precisa do Google Earth para processá-los, use o elemento de dados XML aleatórios, que permite fazer referência a um prefixo de namespace XML e transmitir dados no contexto KML atual. Para obter mais informações, consulte a seção Dados XML aleatórios.

Como adicionar pares de nome/valor digitados

O elemento <Data> é um mecanismo simples, mas poderoso, para adicionar pares de nome/valor não digitados a um elemento KML. A sintaxe para esse elemento é a seguinte:

<ExtendedData>                       
 <Data name="string">
  <displayName>...</displayName>    <!-- string -->
    <value>...</value>                <!-- string -->
 </Data> </ExtendedData>

O atributo name é um código exclusivo para esse dado. O elemento <displayName> é usado quando você deseja exibir o nome desses dados de uma forma simples. O <displayName> pode conter CDATA que inclua espaços, URLs e hiperlinks.

Veja um exemplo de um marcador que contém dados personalizados sobre diversos buracos em um campo de golfe:

<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 tela mostra como os elementos <Data> são, por padrão, exibidos em uma tabela no balão do marcador:

Exemplo de dados usando o estilo padrão para o balão

Revisão: como usar o elemento BalloonStyle como um modelo

Em KML, é possível definir um estilo uma vez e atribuir um código a ele. Depois de definir o estilo dessa maneira, é possível fazer referência a ele várias vezes no arquivo KML (ou em outros arquivos KML) usando o elemento <styleUrl>. Um estilo definido dessa maneira é chamado estilo compartilhado. O elemento <text> em <BalloonStyle> suporta substituição de entidades. Os valores individuais podem ser substituídos para cada instância da entidade. As entidades padrão que podem ser substituídas são as seguintes:

$[name]
Substituída pelo nome do marcador
$[description]
Substituída pela descrição do marcador
$[address]
Substituída pelo endereço do marcador
$[id]
Substituída pelo ID do marcador
$[Snippet]
Substituída pelo snippet do marcador
$[geDirections]
Substituída pelas orientações de rota Para/De do marcador

Substituição de entidades para elementos de dados estendidos

O Google Earth também suporta a substituição de entidades de determinados elementos de dados estendidos no elemento <text> de <BalloonStyle>. As entidades a seguir podem ser referenciadas no elemento <text>:

Variável Substituída por Exemplo
$[name_attribute_of_Data_element] Conteúdo do elemento <value> holeNumber, holeYardage
$[name_attribute_of_Data/displayName] Conteúdo do elemento <displayName> Número do buraco, Jarda do buraco

Veja um exemplo que cria um modelo <BalloonStyle> para o exemplo do campo de golfe. Para cada balão do marcador, o Google Earth substitui o nome do marcador e grava informações contendo o número do buraco, par e a jarda de cada buraco: 

<?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>

Veja uma captura de tela desse exemplo:

Exemplo de dados usando o estilo padrão para o balão

Veja um exemplo mais realista de como o elemento <displayName> seria usado. Essa técnica destina-se à localização do texto e a uma formatação mais elaborada.

<?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>

Veja um exemplo de balão usando esse modelo de estilo de balão:

Como adicionar dados digitados a um elemento

Os elementos <Schema> e <SchemaData> permitem adicionar dados digitados a um elemento. Alguns aplicativos GIS e de programação exigem esse elemento, pois lidam com dados digitados.

Visão geral da adição de dados digitados

Para adicionar um tipo personalizado a um elemento KML, execute duas tarefas básicas:

  1. Crie o elemento <Schema>, que declara seu novo tipo.
  2. Crie instâncias do novo tipo usando o elemento <SchemaData>.

Declare o elemento "Schema"

O elemento "Schema" declara um tipo estruturado. <Schema> é sempre um filho de <Document>. Um "Document" pode conter zero ou mais elementos "Schema".

O atributo "id"

O elemento <Schema> sempre tem um atributo "id", que é consultado quando instâncias desse tipo são criadas (usando <SchemaData>). Esse ID deve ser exclusivo no arquivo KML.

O atributo "name"

O atributo name, que é usado para substituição de entidades, é opcional.

Sintaxe

O elemento "Schema" tem a seguinte sintaxe:

<Schema name="string" id="ID">   
  <SimpleField type="string" name="string">     
    <displayName>...</displayName>            <!-- string -->   
  </SimpleField> 
</Schema>

Um <SimpleField> sempre tem os atributos name e type. Se não tiver os dois atributos, o campo será ignorado. O atributo "name" é usado para substituição de entidades no elemento <text> de <BalloonStyle>. O tipo de um Simplefield pode ser um dos seguintes:

  • string
  • int
  • uint
  • short
  • ushort
  • float
  • double
  • bool

Defina cada instância dos dados

Use o elemento <SchemaData> para criar uma instância do tipo definido pelo usuário. A sintaxe de <SchemaData> é a seguinte:

<ExtendedData>                   
  <SchemaData schemaUrl="anyURI">
    <SimpleData name=""> ... </SimpleData>       <!-- string -->
  </SchemaData>
</ExtendedData>

O atributo schemaUrl faz referência ao código do esquema que declara o tipo (assim como um styleUrl faz referência ao código de um estilo que já foi declarado).Se schemaUrl for um endereço http, o Google Earth buscará esse arquivo na rede. Pode haver apenas uma instância de um determinado tipo definido pelo usuário por marcador.

Exemplo

O exemplo a seguir declara um tipo definido pelo usuário chamado ScenicVista. Esse tipo contém três campos: TrailHeadName, TrailLength e ElevationGain. O campo TrailHeadName contém valores do tipo string. O campo TrailLength contém valores do tipo double. O campo ElevationGain contém valores do tipo int. O marcador chamado Easy trail contém uma instância desse tipo de usuário. Essa instância tem o valor "Pi in the sky" para seu campo TrailHeadName, o valor de 3.14159 para seu campo TrailLength e o valor de 10 para seu 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>

Exemplo de SchemaData usando o estilo padrão para o balão

Substituição de entidades para "displayName"

O mecanismo "Schema/SchemaData" também suporta a substituição de entidades no elemento <text> do elemento <BalloonStyle>.

O <displayName> de <Schema> permite fornecer uma versão simples para um tipo de dado personalizado. A alteração da string no <Schema> tem o efeito de alterar o <displayName> de todos os elementos que contenham esse tipo.

No elemento <text> do elemento <BalloonStyle>, use a sintaxe a seguir para qualificar o <displayName>:

$[TYPENAME/TYPEFIELD/displayName]

em que:

TYPENAME
é o atributo name de <Schema>
TYPEFIELD
é o atributo name de <SimpleField>
displayName
é o elemento <displayName> em <SimpleField>

O código a seguir adiciona um modelo "BalloonStyle" ao exemplo "SchemaData" anterior. Como no exemplo do campo de golfe, o modelo é criado usando os elementos <Style>, <BalloonStyle> e <text> no início do documento. Cada marcador no arquivo faz referência a esse modelo de estilo (chamado "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>

Exemplo de SchemaData usando um modelo de BalloonStyle

Compare o balão criado usando um modelo de BalloonStyle para o estilo de balão padrão com os mesmos dados mostrados na captura de tela anterior.

Como adicionar dados XML aleatórios a um elemento

A maneira mais simples de adicionar dados de usuário a um elemento é adicionar os dados diretamente como um valor <ExtendedData>. O Google Earth preserva esses dados, mas não os processa.

Os elementos de dados personalizados adicionados dessa forma precisam incluir um prefixo namespace (xmlns:prefix="namespace"). Esse prefixo pode ser adicionado ao elemento <kml> ou <ExtendedData>. O prefixo de namespace externo precisa qualificar cada instância dos dados do usuário, como mostra o exemplo a seguir: 

<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>

Voltar ao início