Adding Custom Data (original) (raw)

KML offers three ways to add custom data to a KML Feature. Which approach you choose depends on the kind of data you're adding as well as how you plan to use the data in your KML presentation. Specifically, the element provides the following mechanisms:

• element - allows you to add untyped name/value pairs to the user data associated with a given Feature (NetworkLink, Placemark, GroundOverlay, PhotoOverlay, ScreenOverlay, Document, or Folder). These name/value pairs are displayed in the balloon by default. This information can also be used for entity replacement in the element of . (See the section on Using the BalloonStyle Element as a Template.)
• and elements - allow you to add typed data to the user data associated with a given Feature.
• Arbitrary XML data - allows you to preserve user data within a KML file. Google Earth passes this data along with the file and saves it, but does not use it.

Note: These three mechanisms can be combined in the same file. If you're adding different types of data from different sources, it may be appropriate to use the typed data approach (Schema/SchemaData) for some of the custom data and to use untyped data (Data) for other custom data.

Which Approach Should You Use?

In most cases the element offers the simplest and most powerful mechanism for adding untyped data to a KML Feature. This method is relatively easy to implement, and it offers the advantage of facilitating the use of a BalloonStyle template, which can be applied to all Placemarks in a KML file. (See Entity Replacement for Extended Data Elements for an example of this use.)

The and elements allow you to add typed user data. These elements are offered primarily for users with GIS (Geographic Information System) data. If you have typed data that is used by an external computer application, you will probably need to use the and elements to add structured data types to a Feature. (Google Earth does not use this typed information, but your other application may require it.) Casual users wil probably not need the more technical aspects offered by this mechanism. Like , facilitates use of templates for BalloonStyle.

If you simply need to pass data along with a KML file and do not need Google Earth to process the data, use the arbitrary XML data feature, which allows you to reference an XML namespace prefix and pass along the data in the current KML context. For more information, see the section on Arbitrary XML Data.

Adding Untyped Name/Value Pairs

The element is a simple yet powerful mechanism for adding untyped name/value pairs to a KML Feature. The syntax for this element is as follows:

                       

  ...   
   ...               

The name attribute is a unique ID for this piece of data. The element is used when you want to display the name of this data in a user-friendly form. The can contain CDATA that includes spaces, URLs, and hyperlinks.

Here is an example of a Placemark that contains custom data about several holes in a golf course:

This screen capture shows how the elements are, by default, displayed in a table in the Placemark's balloon:

Data example using default styling for the balloon

Review: Using the BalloonStyle Element as a Template

In KML, you can define a Style once and assign an ID to it. After defining the Style in this manner, you can reference it multiple times within the KML file (or within other KML files) using the element. A style defined in this way is referred to as a shared style. The element within supports entity replacement. Individual values can be substituted for each instance of the entity. Standard entities that can be replaced are as follows:

$[name]

Replaced with the name of the Placemark

$[description]

Replaced with the description of the Placemark

$[address]

Replaced with the address of the Placemark

$[id]

Replaced with the ID of the Placemark

$[Snippet]

Replaced with the Snippet of the Placemark

$[geDirections]

Replaced with the To/From driving directions of the Placemark

Entity Replacement for Extended Data Elements

Google Earth also supports entity replacement of certain extended data elements within the element of . The following entities can be referenced within the element:

Here is an example that creates a template for the golf course example. For each Placemark balloon, Google Earth substitutes the name of the Placemark and then writes out information containing the hole number, par, and yardage for each individual hole:

Here is a screen capture of this example:

Data example using default styling for the balloon

Here is a more realistic example of how the element would be used. This technique lends itself to localization of the text and more elaborate formatting.

Here is an example of a balloon using this balloon style template:

Adding Typed Data to a Feature

The and elements allow you to add typed data to a Feature. Certain GIS and programming applications require this feature because they deal with typed data.

Overview of Adding Typed Data

To add a custom type to a KML Feature, you perform two basic tasks:

1. Create the element, which declares your new type.
2. Create instances of the new type using the element.

Declare the Schema Element

The Schema element declares a structured type. is always a child of . A Document can contain zero or more Schema elements.

The id Attribute

The element always has an id attribute, whish is referenced when instances of this type are created (using ). This ID must be unique within the KML file.

The name Attribute

The name attribute, which is used for entity replacement, is optional.

Syntax

The Schema element has the following syntax:

A always has both name and type attributes. If it does not have both attributes, the field is ignored. The name attribute is used for entity replacement in the element of . The type of a Simplefield can be one of the following:

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

Define Each Instance of the Data

Use the element to create an instance of the user-defined type. The syntax for is as follows:

                    ...

The schemaUrl attribute references the id of the Schema that declares the type (just as a styleUrl references the id of a Style that has already been declared).If schemaUrl is an http address, Google Earth fetches this file across the network. There can be only one instance of a given user-defined type per Placemark.

Example

The following example declares a user-defined type named ScenicVista. This type contains three fields: TrailHeadName, TrailLength and ElevationGain. The TrailHeadName field contains values of type string. The TrailLengt_h field contains values of type double. The ElevationGain field contains values of type int. The Placemark named Easy trail contains an instance of this user type. This instance has a value of "Pi in the sky"_ for its TrailHeadName field, a value of 3.14159 for its TrailLength field, and a value of 10 for its ElevationGain field.

SchemaData example using default styling for the balloon

Entity Replacement for displayName

The Schema/SchemaData mechanism also supports entity replacement in the element of the element.

The of allows you to supply a user friendly version for a custom data type. Changing the string once in the has the effect of changing the for all Features that contain that type.

In the element of the element, use the following syntax to qualify the :

$[TYPENAME/TYPEFIELD/displayName]

where

TYPENAME

is the name attribute of

TYPEFIELD

is the name attribute of

displayName

is the element within

The following code adds a BalloonStyle template to the previous SchemaData example. As in the Golf Course example, the template is created using the

SchemaData example using a BalloonStyle template

Compare the balloon created using a BalloonStyle template to the default balloon style for the same data shown in the previous screen capture.

Adding Arbitrary XML Data to a Feature

The simplest way to add user data to a Feature is to add the data directly as a value of . Google Earth preserves this data but does not process it.

Custom data elements added in this way need to include a namespace prefix (xmlns:prefix="namespace"). This prefix can be added to the element or to the element. The external namespace prefix must qualify each instance of user data, as shown in the following example:

Back to top