require(["esri/dijit/Legend"], function(Legend) { /* code goes here */ });
Description
(Added at v2.1)
The legend dijit displays a label and symbol for some or all of the layers in the map. The label and symbol is based on the symbol or renderer for each layer. To view an example of how to set the labels in the legend using a renderer, see
this sample.
The legend will respect scale dependencies and only display layers and sublayers that are currently visible in the map. The legend automatically updates if the visibility of a layer or sublayer changes. Optionally, either of these two behaviors can be turned off.
The legend supports the following layer types:
ArcGISDynamicMapServiceLayer
,
ArcGISTiledMapServiceLayer
,
FeatureLayer
,
CSVLayer
,
KMLLayer
, and
WMSLayer
.
If the layer is an
ArcGISDynamicMapServiceLayer
or
ArcGISTiledMapServiceLayer
created using ArcGIS Server 10.0 SP1 or higher the legend is generated using the REST Map Service legend resource:
http://mapservice-url/legend
.
If the layers are version 10 or lower the legend is created using the
ArcGIS.com legend service. In order to use the ArcGIS.com legend service your map service needs to be publicly accessible and your application must be able to access ArcGIS.com.
Samples
Search for
samples that use this class.
Constructors
CSS
esri/dijit/Legend | Download source
esriLegendGroupLayer | Define the styles for the node that displays group layer information. |
esriLegendLayer | Define the style for the node that displays layer swatches. |
esriLegendLayerLabel | Define the style for the name and title displayed for layers. |
esriLegendMsg | Class associated with the div that displays informational messages. |
esriLegendService | Define the style for the node where the legend item for a service is rendered. |
esriLegendServiceLabel | Define the style for the node that displays the name and title of the service. |
Properties
Methods
Constructor Details
Creates a new Legend dijit. Should be called after all the layers have been loaded in the map, typically in the map's onLayerAddResult event.
Parameters:
<Object > params |
Required |
Parameters used to configure the dijit. See the list below for details. |
<Node | String > srcNodeRef |
Required |
Reference or id of the HTML element where the widget should be rendered. |
params
properties:
<Number > arrangement |
Optional |
Specify the alignment of the legend within the HTML element where the legend is rendered. The default value of ALIGN_LEFT displays the symbol on the left side of the label. Valid values are:
esri.dijit.Legend.ALIGN_LEFT
esri.dijit.Legend.ALIGN_RIGHT
|
<Boolean > autoUpdate |
Optional |
When false, the legend will not automatically update if the map changes scale or when layers are added are removed from the map. Call refresh to force a legend update. The default value is true. Added at v3.10 |
<Object[] > layerInfos |
Optional |
Specify a subset of the layers in the map to display in the legend. If not set, all layers in the map will display in the legend. The order of the layers in the legend depends on the layerInfo array. See the layerInfos property description for a description of its object properties. |
<Map > map |
Required |
Reference to the map. |
<Boolean > respectCurrentMapScale |
Optional |
When true the legend will update with every scale change and displays only the layers and sub layers that are visible in the current map scale. When false, the legend does not update on every scale change and all layers and sub layers will be displayed. The default value is true. |
Sample:
require([
"esri.Map", "esri/dijit/Legend", ...
], function(Map, Legend, ... ) {
var map = new Map( ... );
var legend = new Legend({
map: map
}, "legendDiv");
legend.startup();
...
});
Property Details
Specify a subset of the layers in the map to display in the legend. If not set all layers in the map will display in the legend. The order of the layers in the legend depends on the layerInfo array. See the object specifications table for the structure of the layerInfos
object.
Object Specifications: <layerInfos
>
<Boolean > defaultSymbol |
Optional |
When false, the default symbol for the renderer will not display in the legend. The default value is true. Only applicable for layers of type esri.layers.FeatureLayer. Added at version 3.1 |
<Number[] > hideLayers |
Optional |
List of sublayer ids that will not be displayed in the legend even if they are visible in the map. Added at version 3.0 |
<Layer > layer |
Required |
A layer to add to the legend. Valid layer types are: ArcGISTiledMapServiceLayer,ArcGISDynamicMapServiceLayer. |
<String > title |
Optional |
Specify a title for the layer. If no title is specified the service name is used. |
Reference to the map. (Added at v3.15)
Method Details
Destroys the legend. Call destroy() when the widget is no longer needed by the application.
Refresh the legend. Takes an optional list of layerInfos to replace the layers setup by the legend constructor. Calling refresh is only necessary when layerInfos is used in the Legend constructor, otherwise the legend will refresh the layers automatically.
Sample:
legend.refresh([{layer:USLayer, title:'Homeland Security'}]);
Finalizes the creation of the legend . Call startup() after creating the widget when you are ready for user interaction.
Sample:
legend.startup();