KML Layers
KML layers are defined using the XML-based Keyhole Markup Language, which is designed to store geographic data. Many mapping applications support KML, including Google Earth, Google Maps, and ArcGIS Server. For more information, see the Open Geospatial Consortium's specification for KML.
To add a KML layer to an Essentials site, the file must have a .kml or .kmz file extension. In addition to adding KML layers to a site, sites can inherit KML layers from web maps.
Supported Features
Essentials uses Esri's JavaScript API to implement KML support. Esri's JavaScript API does not support all KML features. KML features that are not supported by the Esri JavaScript API are also not supported by Essentials. For a list of the API's supported features, see “Supported Features” at the ArcGIS API for JavaScript KMLLayer documentation.
If your System does not have Internet Access
By default, Essentials uses a KML utility service provided by ArcGIS.com to process KML layers. This requires Internet access. If your system does not have access to the Internet and you have Portal for ArcGIS, you can configure Essentials to use the KML utility service that is hosted by Portal for ArcGIS. For instructions, see Override the Default KML Utility Service.
KML Layers and the Map
In Essentials, KML layers have a map service component, but no layer component. If the KML definition contains folders (<Folder> elements), the folders show on the Layer List tab in Manager, but they do not show on the Map Services tab or in layer themes. You cannot edit KML folders or change their visibility in Manager; however, end users can turn the visibility of KML folders on and off in the viewer.
In the legend for a KML layer, viewers use the value of the style's ID (<Style id="">) to label the color swatches. If you own the KML layer, you can pick IDs that are meaningful representations of the style. For example, in a KML layer whose features are earthquakes classified by magnitude, you could set the IDs to M1, M2, M3, and so on, to represent Magnitude 1, Magnitude 2, Magnitude 3. (Note that style IDs cannot contain spaces or special characters.)
Map tips display the balloon (<BalloonStyle> element), if one is defined. If a balloon is not defined, then map tips display the <description>. You can use the Snippet in map tips instead of the <description>, if you want.
Similarly, the Results List displays the <description>, or you can use the Snippet in the Results List instead.
Viewer Support
The Geocortex Viewer for HTML5 does not support the following features for KML layers:
-
Search, query, and filter operations
-
Offline mode
-
Printing KML ground overlays
Esri's JavaScript API does not support all KML features. KML features that are not supported by the Esri JavaScript API are also not supported by Essentials. For a list of the API's supported features, see “Supported Features” at the ArcGIS API for JavaScript KMLLayer documentation.
Essentials does not validate the KML Service URL. If your KML service is not configured properly or is missing, and the viewer cannot connect to the utility service hosted at ArcGIS.com, KML layers do not appear on the map.
Enable HTML Rendering in an HTML5 Viewer
By default, viewers display the value of a KML feature's <description> element in the Results List and in map tips. KML <description> elements can contain HTML markup. For an HTML5 viewer to render the markup, the viewer's Allow Unsafe Content setting must be enabled. If Allow Unsafe Content is disabled, end users will see the markup, instead of what the markup represents.
Example of KML features without HTML rendering (left) and with HTML rendering (right)
If you use the <Snippet> element instead of the <description> element in the Results List and map tips, you do not need to enable HTML rendering, because the <Snippet> element cannot contain HTML markup. See Use a KML Layer's Snippet Element in a Viewer's Results List and Use a KML Layer's Snippet Element in a Viewer's Map Tips.
To enable HTML rendering in an HTML5 viewer:
Enabling HTML rendering in a viewer enables HTML rendering for all of the KML and GeoRSS layers in the site that the viewer belongs to.
-
In
beside the viewer. -
In the side panel, click Application.
-
Select the Allow Unsafe Content checkbox.
-
Click Apply Changes.
Use a KML Layer's Snippet Element in a Viewer's Results List
By default, HTML5 viewers display the value of a KML feature's <description> element in the Results List. You can configure an HTML viewer to display a KML layer's <Snippet> element in the Results List, instead of the <description> element.
To use the Snippet element in an HTML5 viewer's Results List:
-
In
beside the viewer. -
In the side panel, click Look and Feel.
-
In the Results List area, select Feature Description from the Content Field drop-down list.
-
Click Apply Changes.
Use a KML Layer's Snippet Element in a Viewer's Map Tips
By default, HTML5 viewers display the value of a KML feature's description element in map tips. You can configure an HTML viewer to display a KML layer's Snippet element in map tips, instead of the description element.
To use the Snippet element in an HTML5 viewer's map tips:
-
In
beside the viewer. -
In the side panel, click Look and Feel.
-
In the Map Tips area, select Feature Description from the Content Field drop-down list.
-
Click Apply Changes.
Override the Default KML Utility Service
By default, Essentials uses a KML service hosted at ArcGIS.com. Essentials accepts a KML Service URL if your site cannot access the hosted KML service. A configured KML service is only required in the following cases:
-
You need to process KML layers that are not publicly accessible from the Internet.
-
Your viewer cannot access the Internet.
If you use Portal for ArcGIS, you can set the KML Service URL to use its built-in KML service.
To configure a KML Service URL for Portal for ArcGIS:
-
In
-
Click the KML tab.
-
Specify your KML Service URL.
A typical Portal for ArcGIS installation's KML service URL is
http://your.portal-domain.com/arcgis/sharing/kml. -
Click Apply Changes.