Menambahkan Data Kustom

KML menawarkan tiga cara untuk menambahkan data khusus ke Fitur KML. Pendekatan yang Anda pilih bergantung pada jenis data yang ditambahkan serta cara Anda menggunakan data tersebut dalam presentasi KML. Secara khusus, elemen <ExtendedData> menyediakan mekanisme berikut:

  • Elemen <Data> - memungkinkan Anda menambahkan pasangan nama/nilai yang tidak berjenis ke data pengguna yang terkait dengan Fitur tertentu (NetworkLink, Penanda Letak, GroundOverlay, PhotoOverlay, ScreenOverlay, Dokumen, atau Folder). Pasangan nama/nilai ini ditampilkan dalam balon secara default. Informasi ini juga dapat digunakan untuk penggantian entitas dalam elemen <text> <BalloonStyle>. (Lihat bagian tentang Menggunakan Elemen BalloonStyle sebagai Template).
  • Elemen <Schema> dan <SchemaData> - memungkinkan Anda menambahkan data yang diketik ke data pengguna yang terkait dengan Fitur tertentu.
  • Data XML arbitrer - memungkinkan Anda mempertahankan data pengguna dalam file KML. Google Earth meneruskan data ini dengan file tersebut dan menyimpannya, tetapi tidak menggunakannya.

Catatan: Ketiga mekanisme ini dapat digabungkan dalam file yang sama. Jika Anda menambahkan berbagai jenis data dari sumber yang berbeda, sebaiknya gunakan pendekatan data yang diketik (Schema/SchemaData) untuk beberapa data kustom dan untuk menggunakan data tanpa jenis (Data) untuk data kustom lainnya.

Pendekatan Mana yang Harus Anda Gunakan?

Dalam sebagian besar kasus, elemen <Data> menawarkan mekanisme yang paling sederhana dan andal untuk menambahkan data tanpa jenis ke Fitur KML. Metode ini relatif mudah diterapkan, dan menawarkan keuntungan memfasilitasi penggunaan template BalloonStyle, yang dapat diterapkan ke semua Penanda Letak dalam file KML. (Lihat Penggantian Entitas untuk Elemen Data yang Diperluas untuk contoh penggunaan ini.)

Elemen <Schema> dan <SchemaData> memungkinkan Anda menambahkan data pengguna dengan jenis. Elemen ini ditawarkan terutama untuk pengguna dengan data GIS (Geographic Information System). Jika Anda telah mengetik data yang digunakan oleh aplikasi komputer eksternal, Anda mungkin perlu menggunakan elemen <Schema> dan <SchemaData> untuk menambahkan jenis data terstruktur ke Fitur. (Google Earth tidak menggunakan informasi yang diketik ini, namun aplikasi Anda yang lain mungkin memerlukannya.) Pengguna biasa mungkin tidak memerlukan aspek teknis lainnya yang ditawarkan oleh mekanisme ini. Seperti <Data>, <SchemaData> memfasilitasi penggunaan template untuk BalloonStyle.

Jika Anda hanya perlu meneruskan data beserta file KML dan tidak memerlukan Google Earth untuk memproses data, gunakan fitur data XML arbitrer, yang memungkinkan Anda mereferensikan awalan namespace XML dan meneruskan data dalam konteks KML saat ini. Untuk informasi selengkapnya, lihat bagian Data XML arbitrer.

Menambahkan Pasangan Nama/Nilai yang Tidak Diketik

Elemen <Data> adalah mekanisme sederhana namun efektif untuk menambahkan pasangan nama/nilai yang tidak berjenis ke Fitur KML. Sintaksis untuk elemen ini adalah sebagai berikut:

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

Atribut name adalah ID unik untuk bagian data ini. Elemen <displayName> digunakan saat Anda ingin menampilkan nama data ini dalam bentuk yang mudah digunakan. <displayName> dapat berisi CDATA yang mencakup spasi, URL, dan hyperlink.

Berikut adalah contoh Penanda Letak yang berisi data khusus tentang beberapa lubang di lapangan 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>

Screenshot ini menunjukkan bagaimana elemen <Data>, secara default, ditampilkan dalam tabel di balon Penanda Letak:

Contoh data yang menggunakan gaya default untuk balon

Ulasan: Menggunakan Elemen BalloonStyle sebagai Template

Di KML, Anda dapat menentukan Gaya sekali dan menetapkan ID untuk gaya tersebut. Setelah menentukan Gaya dengan cara ini, Anda dapat mereferensikannya beberapa kali dalam file KML (atau dalam file KML lainnya) menggunakan elemen <styleUrl>. Gaya yang ditentukan dengan cara ini disebut sebagai gaya bersama. Elemen <text> dalam <BalloonStyle> mendukung penggantian entitas. Nilai individu dapat diganti untuk setiap instance entity. Entitas standar yang dapat diganti adalah sebagai berikut:

$[nama]
Diganti dengan nama Penanda Letak
$[deskripsi]
Diganti dengan deskripsi Penanda Letak
$[alamat]
Diganti dengan alamat Penanda Letak
$[id]
Diganti dengan ID Penanda Letak
$[Cuplikan]
Diganti dengan Cuplikan Penanda Letak
$[geDirections]
Diganti dengan rute mobil Ke/Dari penanda letak

Penggantian Entitas untuk Elemen Data yang Diperluas

Google Earth juga mendukung penggantian entitas elemen data tambahan tertentu dalam elemen <text> <BalloonStyle>. Entitas berikut dapat dirujuk dalam elemen <text>:

Variabel Diganti Dengan Contoh
$[name_attribute_of_Data_element] Konten elemen <value> holeNumber, holeYardage
$[nama_attribute_of_Data/displayName] Konten elemen <displayName> Nomor Lubang, Yard Lubang

Berikut adalah contoh yang membuat template <BalloonStyle> untuk contoh lapangan golf. Untuk setiap balon Penanda Letak, Google Earth mengganti nama Penanda Letak, lalu menulis informasi yang berisi nomor lubang, ruang, dan jarak pengukuran untuk setiap lubang 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>

Berikut screenshot contoh ini:

Contoh data yang menggunakan gaya default untuk balon

Berikut adalah contoh yang lebih realistis tentang bagaimana elemen <displayName> akan digunakan. Teknik ini cocok untuk pelokalan teks dan pemformatan yang lebih rumit.

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

Berikut adalah contoh balon yang menggunakan template gaya balon ini:

Menambahkan Data Berjenis ke Fitur

Elemen <Schema> dan <SchemaData> memungkinkan Anda untuk menambahkan data yang diketik ke Fitur. Aplikasi GIS dan pemrograman tertentu memerlukan fitur ini karena menangani data yang diketik.

Ringkasan Menambahkan Data Berjenis

Untuk menambahkan jenis kustom ke Fitur KML, Anda harus melakukan dua tugas dasar:

  1. Buat elemen <Schema>, yang mendeklarasikan jenis baru Anda.
  2. Buat instance jenis baru menggunakan elemen <SchemaData>.

Mendeklarasikan Elemen Skema

Elemen skema mendeklarasikan jenis terstruktur. <Schema> selalu merupakan turunan dari <Document>. Dokumen dapat berisi nol atau beberapa elemen Schema.

Atribut id

Elemen <Schema> selalu memiliki atribut id, yang direferensikan saat instance jenis ini dibuat (menggunakan <SchemaData>). ID ini harus unik dalam file KML.

Atribut Nama

Atribut name, yang digunakan untuk penggantian entitas, bersifat opsional.

Sintaksis

Elemen skema memiliki sintaksis berikut:

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

<SimpleField> selalu memiliki atribut name dan type. Jika tidak memiliki kedua atribut, kolom akan diabaikan. Atribut nama ini digunakan sebagai pengganti entitas dalam elemen <text> <BalloonStyle>. Jenis Simplefield dapat berupa salah satu dari berikut ini:

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

Menentukan Setiap Instance Data

Gunakan elemen <SchemaData> untuk membuat instance dari jenis buatan pengguna. Sintaksis untuk <SchemaData> adalah sebagai berikut:

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

Atribut schemaUrl mereferensikan id Skema yang mendeklarasikan jenis (seperti styleUrl yang merujuk ke id Style yang telah dideklarasikan).Jika schemaUrl adalah alamat http, Google Earth akan mengambil file ini di seluruh jaringan. Hanya boleh ada satu instance dari jenis yang ditentukan pengguna tertentu per Penanda Letak.

Contoh

Contoh berikut mendeklarasikan jenis buatan pengguna yang bernama ScenicVista. Jenis ini berisi tiga kolom: TrailHeadName, TrailLength dan ElevationGain. Kolom TrailHeadName berisi nilai jenis string. Kolom TrailLength berisi nilai jenis double. Kolom ElevationGain berisi nilai jenis int. Penanda letak bernama Jalur mudah berisi instance jenis pengguna ini. Instance ini memiliki nilai "Pi di langit" untuk kolom TrailHeadName, nilai 3,14159 untuk kolom TrailLength, dan nilai 10 untuk kolom 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>

Contoh schemaData menggunakan gaya default untuk balon

Penggantian Entitas untuk displayName

Mekanisme Schema/SchemaData juga mendukung penggantian entitas dalam elemen <text> elemen <BalloonStyle>.

<displayName> <Schema> memungkinkan Anda menyediakan versi yang mudah digunakan untuk jenis data kustom. Mengubah string sekali di <Schema> memiliki efek mengubah <displayName> untuk semua Fitur yang berisi jenis tersebut.

Dalam elemen <text> elemen <BalloonStyle>, gunakan sintaksis berikut untuk memenuhi syarat <displayName>:

$[TYPENAME/TYPEFIELD/displayName] 

dengan

TYPENAME
adalah atribut name dari <Schema>
JENIS KELAS
adalah atribut name dari <SimpleField>
Nama Tampilan
adalah elemen <displayName> dalam <SimpleField>

Kode berikut menambahkan template BalloonStyle ke contoh SchemaData sebelumnya. Seperti pada contoh Lapangan Golf, template dibuat menggunakan elemen <Style>, <BalloonStyle>, dan <text> di awal Dokumen. Setiap Penanda Letak dalam file merujuk ke template gaya ini (bernama "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>

Contoh schemaData menggunakan template BalloonStyle

Bandingkan balon yang dibuat menggunakan template BalloonStyle dengan gaya balon default untuk data yang sama yang ditampilkan di screenshot sebelumnya.

Menambahkan Data XML Sewenang-wenang ke Fitur

Cara paling sederhana untuk menambahkan data pengguna ke Fitur adalah menambahkan data secara langsung sebagai nilai <ExtendedData>. Google Earth menyimpan data ini tetapi tidak memprosesnya.

Elemen data kustom yang ditambahkan dengan cara ini harus menyertakan namespace awalan (xmlns:prefix="namespace Awalan ini dapat ditambahkan ke elemen <kml> atau ke elemen <ExtendedData>. Awalan namespace eksternal harus memenuhi syarat untuk setiap instance data pengguna, seperti yang ditunjukkan dalam contoh berikut:

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

Kembali ke atas