require(["esri/layers/KMLLayer"], function(KMLLayer) { /* code goes here */ });
Description
(Added at v2.4)
The KMLLayer class is used to create a layer based on a KML file (.kml, .kmz). KML is an XML-based file format used to represent geographic features.
Note: The KMLLayer uses a utility service from ArcGIS.com, therefore your kml/kmz must be publicly accessible on the internet. If your kml/kmz files are behind the firewall you will need to set the
esriConfig.defaults.kmlService
to your own utility service. (Requires Portal for ArcGIS).
require(["esri/config"], function(esriConfig) {
esriConfig.defaults.kmlService = "http://www.example.com/arcgis/sharing/kml";
});
Accessing features from a KML file
Features from the KML file are accessible via the api so you can query features and use them as input to geometry or geoprocessing services. You can access and manipulate a KML layer's features like any other layer. Because of the wide range of feature types that can be stored in a KML file, a KML layer added to a map is internally made up of several layers. An ArcGIS API for JavaScript KML layer can be thought of as more of a group layer rather than a single layer.
Geometries from a KML file are stored as feature layers: one each for points, lines and polygons. Feature layers for a particular geometry type are only created if there are features of that geometry type in the KML file. The getLayers() method returns the layers that make up a KML file. The following code snippet shows how to get a KML layer's layers, checks that a layer has graphics, unions the layer extents and then zooms to the new extent:
var kmlExtent, layers = kml.getLayers();
dojo.forEach(layers, function(lyr) {
if ( lyr.graphics && lyr.graphics.length > 0 ) {
var lyrExtent = esri.geometry.geographicToWebMercator(
esri.graphicsExtent(lyr.graphics)
);
if ( globals.kmlExtent ) {
kmlExtent = kmlExtent.union(lyrExtent);
} else {
kmlExtent = lyrExtent;
}
});
map.setExtent(kmlExtent);
Supported Features
The following KML features are supported at version 2.4:
- Placemarks
- Network links without refresh parameters
- Ground overlays
- Folders
- Point, polyline, and polygon symbology, including icons
- HTML in feature descriptions
Support for the following was added at version 2.5:
- Network links with refresh parameters
- ExtendedData feature attributes
- Time
The following features are not supported:
- Screen overlays
- Regionated KML
- Regions inside network links
Samples
Search for
samples that use this class.
Class hierarchy
esri/layers/Layer
|_esri/layers/KMLLayer
Constructors
new KMLLayer(id, url, options?) | Creates a new KMLLayer based upon the given URL.
The KMLLayer has the following behavior:
- Does not support queries that need to be performed on the server, for example queries with a where clause or non-extent based spatial queries.
|
Properties
Methods
Events
[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.
Events
error | {
error: <Error >
} | Fires when there is a problem retrieving a layer. |
load | {
layer: <Layer >
} | Fires after layer properties for the layer are successfully populated. |
network-link-error | {
error: <Error >
} | Fires when one or more of the layer's network link children fail to load. |
opacity-change | {
opacity: <Number >
} | Fires when the layer opacity has been changed, and returns an object with the opacity value. |
refresh | | Fired after the layer is refreshed. |
refresh-interval-change | | This event is fired when the layer's refreshInterval is modified. |
resume | | Fires when a layer resumes drawing. |
scale-range-change | | Fires when a layer's minScale and/or maxScale is changed. |
scale-visibility-change | | Fires when a layer's scale visibility changes. |
suspend | | Fires when a layer suspends drawing. |
update | | Fires any time a layer has finished loading or updating itself. |
update-end | {
error: <Error >
} | Fires when a layer has finished updating its content. |
update-start | | Fires when a layer begins to update its content. |
visibility-change | {
visible: <Boolean >
} | Fires when the layer visibility has been changed, and returns an object with a Boolean visible property containing the new visibility value of the layer. |
Constructor Details
Creates a new KMLLayer based upon the given URL.
The
KMLLayer
has the following behavior:
- Does not support queries that need to be performed on the server, for example queries with a where clause or non-extent based spatial queries.
Parameters:
<String > id |
Required |
Id to assign to the layer. This id is used for the layer and as the base for all sub layers that are created. |
<String > url |
Required |
URL for a .kml or .kmz file. |
<Object > options |
Optional |
Optional parameters. See options list. View the Layer object for additional options. |
options
properties:
<String > className |
Optional |
Class attribute to set for the layer's node. |
<SpatialReference > outSR |
Optional |
The output spatial reference for the KMLLayer. |
<Number > refreshInterval |
Optional |
Refresh interval of the layer in minutes. Non-zero value sets up automatic layer refresh at the specified interval. |
Sample:
require([
"esri/layers/KMLLayer", ...
], function(KMLLayer, ... ) {
var kmlUrl = 'http://www.ci.redding.ca.us/KML/SacRiverTrail.kml';
kml = new KMLLayer(kmlUrl);
...
});
Property Details
class attribute of the layer's node.
(Added at v3.7)
An array of objects that describe top-level KML features ids and their types. Objects in the array have the following properties:
{
"type":<Number>,
"id": <Number>
}
The type can be one of the following:Folder, GroundOverlay, Line, NetworkLink,Point, Polygon, ScreenOverlay.
An array of KMLFolder objects that describe the folders and nested folders defined in the KML file. Use the parentFolderId and subFolderIds to identify the hierarchical relationship between folders.
ID assigned to the layer. If not assigned, esri.Map assigns value. By default, the ID of the layer is "layer" followed by a number. The ID can be user defined only in the layer constructor.
Sample:
- Setting the layer ID in the layer constructor.
require([
"esri/layers/ArcGISDynamicMapServiceLayer", ...
], function(ArcGISDynamicMapServiceLayer, ... ) {
var population = new ArcGISDynamicMapServiceLayer("http://myserver/arcgis/rest/population/MapServer/Layers", {id:"population"});
...
});
- Setting the layer ID after a layer is initialized.
population.id = "population";
- Retrieving the layer ID.
function getMapLayers() {
for (var j=0, jl=map.layerIds.length; j<jl; j++) {
var currentLayer = map.getLayer(map.layerIds[j]);
alert("id: " + currentLayer.id);
}
}
A link info object with properties that describe the network link. The object has the following properties:
{
"id": <Number>,
"name": <String>,
"description": <String>,
"snippet": <String>,
"visibility": <Number>
"refreshMode": <String>,
"refreshInterval": <Number>,
"viewRefreshMode": <String>,
"viewRefreshTime": <Number>,
"viewBoundScale": <Number>,
"viewFormat": <String>,
"httpQuery": <String>
}
(Added at v2.5)
Set if the layer failed to load. (Added at v3.9)
When the layer is loaded, the value becomes "true", and layer properties can be accessed. The
onLoad event is also fired.
Known values: true | false
Maximum visible scale for the layer. If the map is zoomed in beyond this scale, the layer will not be visible. A value of 0 means the layer does not have a maximum scale. (Added at v3.1)
Default value: 0
Minimum visible scale for the layer. If the map is zoomed out beyond this scale, the layer will not be visible. A value of 0 means the layer does not have a visible scale. (Added at v3.1)
Default value: 0
Opacity or transparency of layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency.
Known values: 0.0 - 1.0
Default value: 1.0
Refresh interval of the layer in minutes. Non-zero value indicates automatic layer refresh at the specified interval. Value of 0 indicates auto refresh is not enabled. (Added at v3.7)
When true, the layer's attribution is displayed on the map. (Added at v3.1)
Known values: true | false
Default value: true
When true, the layer is suspended. A layer is considered to be suspended when one of the following is true:
- The layer is hidden.
- The layer is not visible at the current map scale.
- The layer is explicitly suspended by calling the
Layer.suspend
method.
(Added at v3.1) Known values: true | false
The publicly accessible URL for a .kml or .kmz file.
Visibility of the layer.
Known values: true | false
Default value: true
When true, the layer is visible at the current map scale. (Added at v3.1)
Known values: true | false
Method Details
Adds a new attribute or changes the value of an existing attribute on the layer's node. Removes the attribute if the value is null
or undefined
. (Added at v3.7)
Parameters:
<String > name |
Required |
The name of the attribute. |
<String > value |
Required |
The value of the attribute. Set this value as null to remove the attribute. |
Get the KML feature identified by the input feature info. The table below lists the type of objects returned for the KML feature types.
KML <Feature> | Class name of returned object |
Placemark | Graphic |
GroundOverlay | KMLGroundOverlay |
ScreenOverlay | KMLScreenOverlay (Not Implemented) |
NetworkLink | KMLLayer |
Folder | KMLFolder |
Parameters:
<Object > featureInfo |
Required |
Feature info for the kml feature. |
Sample:
require([
"esri/layers/KMLLayer", "dojo/_base/array", ...
], function(KMLLayer, array, ... ) {
var kmlLayer = new KMLLayer( ... );
var featureInfos = kmlLayer.folders[0].featureInfos;
array.forEach(featureInfos,function(info){
var feature = kmlLayer.getFeature(info);
//do something with the feature here...
});
...
});
Get an array of map layers that were created to draw placemarks, ground and screen overlays. The returned array can have instances of the following layer types: FeatureLayer, MapImageLayer or KMLLayer . This method can be used to override the renderer for feature layers.
Sample:
require([
"esri/layers/KMLLayer", "dojo/_base/array", ...
], function(KMLLayer, array, ... ) {
var kmlLayer = new KMLLayer( ... );
var layers = kmlLayer.getLayers();
array.forEach(layers, function(layer){
if (layer.declaredClass === "esri.layers.FeatureLayer") {
}
else if (layer.declaredClass === "esri.layers.MapImageLayer") {
}
});
...
});
Returns reference to the map control the layer is added to. Returns null
or undefined
if it is not added to a map. (Added at v3.7)
Returns the layer's DOM node. (Added at v3.7)
Sets the visibility of the layer to "false". The layer is not removed, but it is hidden from view.
Returns true if the layer is visible at the given scale. (Added at v3.1)
Parameters:
<Number > scale |
Required |
The scale at which to check if the layer is visible. |
Refreshes the features in the KML Layer.
Resumes layer drawing. (Added at v3.1)
Set the visibility for the specified folder.
Parameters:
<KMLFolder > folder |
Required |
A KML folder. |
<Boolean > isVisible |
Required |
The visibility of the folder and all kml features within the folder. |
Sample:
require([
"esri/layers/KMLLayer", "dojo/_base/array", ...
], function(KMLLayer, array, ... ) {
var kmlLayer = new KMLLayer( ... );
var folders = kmlLayer.folders;
array.forEach(folders,function(folder){
kmlLayer.setFolderVisibility(folder,true);
});
...
});
Set the maximum scale for the layer. (Added at v3.1)
Parameters:
<Number > scale |
Required |
The maximum scale at which the layer is visible. |
Set the minimum scale for the layer. (Added at v3.1)
Parameters:
<Number > scale |
Required |
The minimum scale at which the layer is visible. |
Sets the opacity of the layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency.
Parameters:
<Number > opacity |
Required |
Value from 0 to 1, where 0 is 100% transparent and 1 has no transparency. The default value is 1. |
Sample:
layer.setOpacity(0.5);
Changes the layer's refresh interval to the given value (in minutes). Non-zero value sets up automatic layer refresh at the specified interval. Value of 0 stops auto refresh. (Added at v3.7)
Parameters:
<Number > interval |
Required |
Refresh interval of the layer in minutes. Non-zero value indicates automatic layer refresh at the specified interval. Value of 0 indicates auto refresh is not enabled. |
Set the scale range for the layer. If minScale
and maxScale
are set to 0 then the layer will be visible at all scales. (Added at v3.1)
Parameters:
<Number > minScale |
Required |
The minimum scale at which the layer is visible. |
<Number > maxScale |
Required |
The maximum scale at which the layer is visible. |
Sets the visibility of the layer. When true, the layer is visible.
Parameters:
<Boolean > isVisible |
Required |
Set the visibility of the layer. |
Sets the visibility of the layer to "true".
Suspends layer drawing. (Added at v3.1)
Event Details
[ On Style Events | Connect Style Event ]
Fires when there is a problem retrieving a layer. Should be used in favor of onError. (Added at v3.5)
Fires after layer properties for the layer are successfully populated. This event must be successful before the layer can be added to the map. Should be used in favor of onLoad. (Added at v3.5)
Event Object Properties:
<Layer > layer |
The loaded layer. |
Fires when one or more of the layer's network link children fail to load. (Added at v3.22)
Event Object Properties:
<Error > error |
An error object returned when an error occurred in loading the network link children. |
Fires when the layer opacity has been changed, and returns an object with the opacity value. Should be used in favor of onOpacityChange. (Added at v3.5)
Event Object Properties:
<Number > opacity |
Fires when the layer opacity (transparency) changes. A number property named opacity that indicates the new opacity. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency. |
Fired after the layer is refreshed. If the layer represents a network link it is automatically refreshed based on the network link parameters defined in the linkInfo
property. Layers can be explicitly refreshed by calling the refresh
method. (Added at v3.6)
This event is fired when the layer's refreshInterval
is modified. (Added at v3.7)
Fires when a layer resumes drawing. Should be used in favor of onResume. (Added at v3.5)
Fires when a layer's minScale and/or maxScale is changed. Should be used in favor of onScaleRangeChange. (Added at v3.5)
Fires when a layer's scale visibility changes. The scale visibility changes when a layer is initially visible and becomes invisible because the map scale does not intersect the layer's scale range or vice versa. Should be used in favor of onScaleVisibilityChange. (Added at v3.5)
Fires when a layer suspends drawing. Should be used in favor of onSuspend. (Added at v3.5)
Fires when a layer has finished updating its content. It is the responsibility of the subclass to determine when this event is fired. Should be used in favor of onUpdateEnd. (Added at v3.5)
Event Object Properties:
<Error > error |
Optional argument. The error object is available when an error occurs during the update. |
Fires when a layer begins to update its content. It is the responsibility of the subclass to determine when this event is fired. Should be used in favor of onUpdateStart. (Added at v3.5)
Fires when the layer visibility has been changed, and returns an object with a Boolean visible property containing the new visibility value of the layer. Should be used in favor of onVisibilityChange. (Added at v3.5)
Event Object Properties:
<Boolean > visible |
Fires when the layer visibility changes. A boolean property named visible indicates whether or not the layer is visible after visibility changed. |
Fires when there is a problem retrieving a layer. (Added at v1.3)
Fires after layer properties for the layer are successfully populated. This event must be successful before the layer can be added to the map.
In Internet Explorer, due to resource caching, the onLoad event is fired as soon as the layer is constructed. Consequently you should check whether the layer's loaded property is true before registering a listener for the onLoad event:
Event Object Properties:
<Layer > layer |
The loaded layer. |
Sample: function init() {
//setting initial extent in constructor
var map = new esri.Map("mapDiv", { extent: new esri.geometry.Extent(...) });
//or use set extent method
var map = new esri.Map("mapDiv");
map.setExtent(new esri.geometry.Extent(...));
//add first layer
map.addLayer(...);
}
Fires when the layer opacity has been changed, and returns the opacity value.
Event Object Properties:
<Number > opacity |
Opacity or transparency of layer. Values range from 0.0 to 1.0, where 0.0 is 100% transparent and 1.0 has no transparency. |
Fired after the layer is refreshed. If the layer represents a network link it is automatically refreshed based on the network link parameters defined in the linkInfo
property. Layers can be explicitly refreshed by calling the refresh
method.
This event is fired when the layer's refreshInterval
is modified. (Added at v3.7)
Fires when a layer resumes drawing. (Added at v3.1)
Fires when a layer's minScale and/or maxScale is changed. (Added at v3.1)
Fires when a layer's scale visibility changes. The scale visibility changes when a layer is initially visible and becomes invisible because the map scale does not intersect the layer's scale range or vice versa. (Added at v3.1)
Fires when a layer suspends drawing. (Added at v3.1)
Fires when a layer has finished updating its content. It is the responsibility of the subclass to determine when this event is fired.
Event Object Properties:
<Error > error |
Optional argument. The error object is available when an error occurs during the update. |
Sample: dojo.connect(layer, "onUpdateEnd", layerUpdateCompleted);
function layerUpdateCompleted(error) {
if (error) {
console.log("Update completed with error: ", error);
}
else {
console.log("Update completed");
}
}
Fires when a layer begins to update its content. It is the responsibility of the subclass to determine when this event is fired.
Sample:
dojo.connect(layer, "onUpdateStart", layerUpdateStarted);
function layerUpdateStarted() {
console.log("Update started...");
}
Fires when the layer visibility has been changed, and returns the new visibility.
Event Object Properties:
<Boolean > visbility |
Determines whether the layer is visible on the map. |