Authoring maps for publishing as KML

If you anticipate that users will access your map as KML, there are certain design patterns that you should follow. This topic also contains tips on how to prepare your map so that certain features of KML are available. For example, when someone views your KML service and clicks a point, what appears in the pop-up window? Or, how can you create a high-performance service that uses KML Regions? These are examples of things that you need to set up during the map authoring phase before you publish the service.

What can you include in the map?

You can include both vector and raster layers in your map. Labels that you set on either of these feature types will also be included in the KML.

Once you publish the service, you'll be able to choose whether clients will be able to retrieve the actual vector features or whether they'll see rasterized images of the map. Similarly, you'll be able to choose whether the labels in your map are rasterized and lie flat on the globe or if they stand up on the globe and rotate when the user rotates the map (these are also known as "billboarded" labels).

Working with labels

Labels in your map will be converted to KML. The label text is based on the field you choose on the Labeling tab of the Layer Properties dialog box in ArcMap.

If you have disabled all fields and you still choose to label features, the label text will be based on the Primary Display Field (for more on the Primary Display Field, see Setting field properties, aliases, and table display options in the ArcGIS Desktop Help).

The only label effects that are honored in the KML are size and color. Labeling effects, such as shadows and halos are not transferable to KML. Only one label can be applied per feature.

Setting up descriptions and snippets

Descriptions and snippets are two ways of providing attribute information in KML. The snippet is a short piece of text that describes something (like a title). The description is a longer explanation that can include text, links, pictures, and other media.

Descriptions determine what appears in the informational pop-up window that is displayed when you click a feature. Snippets define text that appears in the table of contents. Both descriptions and snippets can be applied at many levels: at the feature level, layer level, data frame level, and network link level.

Setting up the snippet

By default, snippets are not configured to appear. You can change this by unchecking "Suppress default KML snippet behavior" when publishing a KML network link in Manager. In this case, if a snippet is defined, it will be used. Where no snippet is defined, the first two lines of the description will be used.

If you choose to use snippets, they derive from a field in your data. You choose which field appears in the snippet by giving it the alias "KMLSnippet". You can only give one field this alias.

Setting up the description

You set up the description differently based on whether it will apply to the network link, the data frame, the layer, or the individual feature.

• The description for the network link is only configurable when you publish the service as a network link.

• The description for the data frame is based on what's in the Description box on the General tab of the Data Frame Properties dialog box.

  

• The description for layers is based on what's in the Description box on the General tab of the Layer Properties dialog box.

  

• The description for individual features is formatted by the XSL stylesheet that you specify on the HTML Popup tab in the Layer Properties dialog box in ArcMap. Some sample stylesheets are included in <ArcGIS Install location>\Styles\HTMLPopup.

  

  XSL stylesheets allow you to use your feature attribute values to construct a popup window with any HTML. For example, you could create a link to a geoprocessing task result that returns KMZ, using the attribute values to define the model parameters. This allows you to access real GIS in a KML browser environment. You can also link to the results of layer queries in a similar way, using attribute values as query parameters. Additionally, you can display images or Flash videos referenced by an attribute in your feature. In summary, you can link to any HTML content on the Web.

  KML from queries or geoprocessing tasks will only use the popup if all fields are returned. If you were to return only a subset of fields, the stylesheet could be referencing fields that don't exist, causing unexpected behavior. If all fields are not returned, a simple HTML table of field names and attribute values will be returned.

Long and complex descriptions can cause slower performance in KML client applications. Avoid long descriptions if performance is an issue. To shorten your descriptions, consider including a simple link to a Web page that contains the same material.

If your feature density is very high and your stylesheet is complicated, remember that the stylesheet is applied for each feature and performance may become an issue.

Extruding features

If you want to publish feature classes with 3D attributes, such as z-offsets, or extrude features based on attributes, you must first edit the feature class layer properties in ArcGlobe, save them as a layer file, then add the layer file to an ArcMap document. For example, if you have a polygon feature class with a population density field, you can set the extrusion properties for that class in ArcGlobe, save the feature class as a layer file, then add the layer file to an ArcMap document. The published KML will have a 3D appearance.

The following steps explain how to use ArcGlobe to configure elevation and extrusion in your map:

1. Start ArcGlobe.
2. Add the feature class that will be elevated or extruded.
3. Right-click the layer and click Properties.
4. Use the Elevation and Globe Extrusion tabs on the Properties dialog box to adjust the elevation and extrusion settings. When finished, click OK to close the Properties dialog box.
5. Right-click the name of the layer in the table of contents and click Save As Layer File. Choose a name and location for the layer file and click Save.
6. Exit ArcGlobe.
7. Start ArcMap and open the map document you will be using for your KML service.
8. Click the Add Data button.
9. Navigate to the layer file you created in ArcGlobe and add it to the map. You won't see any of the elevation or extrusion effects in ArcMap, but they will be visible when you publish the map as a KML service.

For a detailed walkthrough of this process, see Tutorial: Publishing a KML service.

Setting up the legend

You can make a legend available that describes the layers in your KML service. The server searches the Layout view of your map document for any legends that are present. If legends are found, they are embedded in the KML.

To create a legend in your map document:

1. In ArcMap, click View and click Layout View.
2. Click Insert and click Legend
3. Complete the Legend wizard to add a legend to your map.

Legends are dynamic and will be updated if you change the symbology of any of your map features or the scale of your map (for layers with scale ranges set). Do not convert your legends to graphics, or they won't be embedded in the KML.

Each legend appears in the KML as a screen overlay. This means that it stays visible on the screen as the user pans and zooms the map. The user can choose where the legend will be placed on the screen from a folder of cardinal locations (for example, north, northwest, west, and so on).

Tip: If you'll just be using this map for KML, you don't have to worry about the positioning of the legend in the ArcMap layout.

Additional examples

For some example workflows of preparing a map document for KML publishing, see KML examples in the ArcGIS Desktop Help.