Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/support
esri/workers
Class: LabelLayer

dojo.require("esri.layers.LabelLayer");

Description

(Added at v3.7)
NOTE: Deprecated as of version 3.14, read below for additional information on the suggested method of labeling.

The LabelLayer inherits from the graphics layer and can be used to display texts and symbols on map. It is a regular layer which can be added to the map in combination with any other feature layers.

Starting with version 3.14, labeling should be handled via the featureLayer.setLabelingInfo() method. Also, the Map's showLabel constructor option should always be set when labeling since most of the labeling parameters are taken directly from the feature layer. It is also possible to set the format parameters, symbols, date, etc. using the LabelClass() as seen in the sample snippet below.

Supported way to label as of version 3.14
//the snippet below shows how you should be labeling as of version 3.14

//make sure the Map's showLabels option is set to true
var map = new Map("map", {
  basemap: "streets-vector",
  center:[-80, 30],
  zoom: 4,
  showLabels : true
});
 
//create featurelayer
var flayer = new FeatureLayer(url, {
  outFields: ["*"] //make sure field to label is specified here in outFields
});


//create a text symbol and renderer to define the style of labels
var labelSymbol = new TextSymbol(); 

var json = {
  "labelExpressionInfo": {"value": "{LocalTime}"},
  "useCodedValues": false,
  "fieldInfos": [{fieldName: "LocalTime",format: { "dateFormat": "shortDate"}}]
};

//create instance of LabelClass
var lc = new LabelClass(json);
lc.symbol = labelSymbol; // symbol also can be set in LabelClass' json
flayer.setLabelingInfo([ lc ]);
Labeling prior to version 3.14 (deprecated method)
//the snippet below shows how labeling was handled prior to version 3.14

//create instance of map
var map = new Map("map", {
  basemap: "streets-vector",
  center:[-80, 30],
  zoom: 4
});

var flayer = new FeatureLayer(url, {
  outFields: ["*"] //make sure field to label is specified here in outFields
});

//create a text symbol and renderer to define the style of labels
var labelSymbol = new TextSymbol(); 
var labelRenderer = new SimpleRenderer(labelSymbol);
var labels = new LabelLayer({ id: "labels" });
  
labels.addFeatureLayer(flayer, labelRenderer, "{" + labelField + "}");

//add the label layer to the map
map.addLayer(labels);
For additional information showing how this can be done, please refer to the Labeling features client-side tutorial.

Samples

Search for samples that use this class.

Class hierarchy

esri/layers.Layer
|_esri/layers.GraphicsLayer
  |_esri/layers.LabelLayer

Constructors

NameSummary
new esri.layers.LabelLayer(params?)Creates a new Label layer.

Properties

NameTypeSummary
classNameStringclass attribute of the layer's node.
dataAttributesString | String[]List of attribute fields added as custom data attributes to graphics node.
graphicsGraphic[]The array of graphics that make up the layer.
idStringID assigned to the layer.
infoTemplateInfoTemplateThe info template for the layer.
loadErrorErrorSet if the layer failed to load.
loadedBooleanWhen the layer is loaded, the value becomes "true", and layer properties can be accessed.
maxScaleNumberMaximum visible scale for the layer.
minScaleNumberMinimum visible scale for the layer.
opacityNumberOpacity or transparency of layer.
refreshIntervalNumberRefresh interval of the layer in minutes.
rendererRendererRenderer assigned to the GraphicsLayer.
showAttributionBooleanWhen true, the layer's attribution is displayed on the map.
stylingBooleanIndicates whether the layer is responsible for styling graphics.
surfaceTypeStringType of vector graphics surface used to draw graphics.
suspendedBooleanWhen true, the layer is suspended.
urlStringURL to the ArcGIS Server REST resource that represents a map service.
visibleBooleanVisibility of the layer.
visibleAtMapScaleBooleanWhen true, the layer is visible at the current map scale.

Methods

NameReturn typeSummary
addFeatureLayer(featureLayer, renderer?, textExpression?)NoneAdds reference to the feature layer which is labeled.
attr(name, value)LayerAdds a new attribute or changes the value of an existing attribute on the layer's node.
clear()NoneClears all graphics.
disableMouseEvents()NoneDisables all mouse events on the graphics layer.
enableMouseEvents()NoneEnables all mouse events on the graphics layer.
getFeatureLayer(index)FeatureLayerReturns reference to the feature layer which features will be labeled.
getMap()MapReturns reference to the map control the layer is added to.
getNode()HTMLElementReturns the layer's DOM node.
hide()NoneSets the visibility of the layer to "false".
isVisibleAtScale(scale)BooleanReturns true if the layer is visible at the given scale.
redraw()NoneRedraws all the graphics in the layer.
remove(graphic)GraphicRemoves a graphic.
resume()NoneResumes layer drawing.
setInfoTemplate(infoTemplate)NoneSpecify or change the info template for a layer.
setMaxScale(scale)NoneSet the maximum scale for the layer.
setMinScale(scale)NoneSet the minimum scale for the layer.
setOpacity(opacity)NoneInitial opacity or transparency of layer.
setRefreshInterval(interval)LayerChanges the layer's refresh interval to the given value (in minutes).
setRenderer(renderer)NoneSets the renderer for the graphics layer.
setScaleRange(minScale, maxScale)NoneSet the scale range for the layer.
setVisibility(isVisible)NoneSets the visibility of the layer.
show()NoneSets the visibility of the layer to "true".
suspend()NoneSuspends layer drawing.

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

NameEvent ObjectSummary
click
{
  event: <Object>
}
Fires when a graphic has been clicked.
dbl-clickFires when a graphic has been double clicked.
error
{
  error: <Error>
}
Fires when there is a problem retrieving a layer.
graphic-add
{
  graphic: <Graphic>
}
Fires when a graphic is added to the GraphicsLayer.
graphic-draw
{
  graphic: <Graphic>
}
Fires when a graphic is drawn.
graphic-node-add
{
  graphic: <Graphic>,
  node: <HTMLElement>
}
Fires when a graphic's DOM node is created and added to the layer.
graphic-node-remove
{
  graphic: <Graphic>,
  node: <HTMLElement>
}
This event is fired when a graphic's DOM node is removed (consider the node destroyed).
graphic-remove
{
  graphic: <Graphic>
}
Fires when a graphic is removed from the GraphicsLayer.
graphics-clearFires when all graphics in the GraphicsLayer are cleared.
load
{
  layer: <Layer>
}
Fires after layer properties for the layer are successfully populated.
mouse-down<MouseEvent> mouseEventFires when a mouse button is pressed down and the mouse cursor is on a graphic.
mouse-drag<MouseEvent> mouseEventFires while the mouse is being dragged until the mouse button is released.
mouse-move<MouseEvent> mouseEventFires as the mouse moves through a graphic on the GraphicsLayer.
mouse-out<MouseEvent> mouseEventFires as the mouse exits a graphic on the GraphicsLayer.
mouse-over<MouseEvent> mouseEventFires when the mouse first enters into a graphic on the GraphicsLayer.
mouse-up<MouseEvent> mouseEventFires when a mouse button is released and the mouse cursor is on a graphic.
opacity-change
{
  opacity: <Number>
}
Fires when the layer opacity has been changed, and returns an object with the opacity value.
refresh-interval-changeThis event is fired when the layer's refreshInterval is modified.
resumeFires when a layer resumes drawing.
scale-range-changeFires when a layer's minScale and/or maxScale is changed.
scale-visibility-changeFires when a layer's scale visibility changes.
suspendFires when a layer suspends drawing.
updateFires any time a layer has finished loading or updating itself.
update-end
{
  error: <Error>
}
Fires when a layer has finished updating its content.
update-startFires 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

new esri.layers.LabelLayer(params?)

Creates a new Label layer.
Parameters:
<Object> params Optional Constructor parameters.
params properties:
<String> id Optional ID assigned to the layer.
<String> mode Optional Display mode for the label layer. Mode Valid values are "DYNAMIC" and "STATIC". Default is "STATIC".
Starting with version 3.10, the default is to label features when a feature is visible and not continuously reposition labels. Prior to this, labels were repositioned on every map navigation event (pan or zoom). The pre-3.10 behavior of continuously re-labeling is available by specifying mode: "dynamic" when creating a label layer.
Property Details

<String> className

class attribute of the layer's node. (Added at v3.7)

<String | String[]> dataAttributes

List of attribute fields added as custom data attributes to graphics node. Applicable only when layer surfaceType is "svg". (Added at v3.7)

<Graphic[]> graphics

The array of graphics that make up the layer.

<String> id

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.
    population = new esri.layers.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=myMap.layerIds.length; j<jl; j++) {
        var currentLayer = myMap.getLayer(myMap.layerIds[j]);
        alert("id: " + currentLayer.id);
      }
    }
    

<InfoTemplate> infoTemplate

The info template for the layer. (Added at v3.9)

<Error> loadError

Set if the layer failed to load. (Added at v3.9)

<Boolean> loaded

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

<Number> maxScale

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

<Number> minScale

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

<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.
Known values: 0.0 - 1.0
Default value: 1.0

<Number> refreshInterval

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)

<Renderer> renderer

Renderer assigned to the GraphicsLayer. (Added at v1.4)

<Boolean> showAttribution

When true, the layer's attribution is displayed on the map. (Added at v3.1)
Known values: true | false
Default value: true

<Boolean> styling

Indicates whether the layer is responsible for styling graphics. When true, styling is based on graphics symbol or the layer's renderer. When false, graphics styling is disabled. Applicable only when layer surfaceType is "svg". (Added at v3.7)
Known values: true | false

<String> surfaceType

Type of vector graphics surface used to draw graphics. (Added at v3.7)
Known values: "svg" | "canvas-2d" | "vml"
Default value: "svg" on all browsers - except IE8 or earlier where "vml" is used to draw graphics.

<Boolean> suspended

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

<String> url

URL to the ArcGIS Server REST resource that represents a map service. To obtain the URL, use Services Directory. An example URL for the Street Map service on ArcGIS Online is:
https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer. (Added at v1.2)

<Boolean> visible

Visibility of the layer.
Known values: true | false
Default value: true

<Boolean> visibleAtMapScale

When true, the layer is visible at the current map scale. (Added at v3.1)
Known values: true | false
Method Details

addFeatureLayer(featureLayer, renderer?, textExpression?)

Adds reference to the feature layer which is labeled. You may add as many feature layers as you need.
Parameters:
<FeatureLayer> featureLayer Required The feature layer to be added to the label layer. Use FeatureLayer.MODE_ONDEMAND to improve the performance. Be sure the field(s) you would like to display is included in outFields.
var featureLayer = new FeatureLayer(
  "http://sampleserver6.arcgisonline.com/arcgis/rest/services/WorldTimeZones/MapServer/0",
  {
    mode: FeatureLayer.MODE_ONDEMAND,
    outFields: ["CITY_NAME"]
  }
);
<SimpleRenderer | UniqueValueRenderer | ClassBreaksRenderer> renderer Optional The renderer used to render text labels. For most applications SimpleRenderer is best choice, but you can use UniqueValueRenderer or ClassBreaksRenderer.
var renderer = new SimpleRenderer(symbol);
<Object> textExpression Optional An expression determining what text and field(s) will be displayed as in labels.
"{CITY_NAME}"

attr(name, value)

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)
Return type: Layer
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.

clear()

Clears all graphics. It is not recommended to call clear() on a FeatureLayer as the layer automatically manages fetching (from the service) and clearing graphics based on its mode. Explicitly calling clear() to clear the graphics will interfere with the integrity of this process. For feature layers, we recommend using applyedits() to add, delete, and update features.
Sample:
graphicsLayer.clear();

disableMouseEvents()

Disables all mouse events on the graphics layer.

enableMouseEvents()

Enables all mouse events on the graphics layer.

getFeatureLayer(index)

Returns reference to the feature layer which features will be labeled.
Return type: FeatureLayer
Parameters:
<Number> index Required Index of the referenced feature layer.

getMap()

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)
Return type: Map

getNode()

Returns the layer's DOM node. (Added at v3.7)
Return type: HTMLElement

hide()

Sets the visibility of the layer to "false". The layer is not removed, but it is hidden from view.

isVisibleAtScale(scale)

Returns true if the layer is visible at the given scale. (Added at v3.1)
Return type: Boolean
Parameters:
<Number> scale Required The scale at which to check if the layer is visible.

redraw()

Redraws all the graphics in the layer. This method is functionally equivalent to refresh. (Added at v3.3)

remove(graphic)

Removes a graphic. It is not recommended to call remove() on a FeatureLayer as the layer automatically manages fetching (from the service) and clearing graphics based on its mode. Explicitly calling remove() to remove the graphics will interfere with the integrity of this process. For feature layers, we recommend using applyedits() to add, delete, and update features.
Return type: Graphic
Parameters:
<Graphic> graphic Required The graphic to remove.

resume()

Resumes layer drawing. (Added at v3.1)

setInfoTemplate(infoTemplate)

Specify or change the info template for a layer. (Added at v2.2)
Parameters:
<InfoTemplate> infoTemplate Required The new info template.
Sample:

var cityLayer = new esri.layers.GraphicsLayer();

var infoTemplate = new esri.InfoTemplate("${CITY_NAME}","${*}");

cityLayer.setInfoTemplate(infoTemplate);

setMaxScale(scale)

Set the maximum scale for the layer. (Added at v3.1)
Parameters:
<Number> scale Required The maximum scale at which the layer is visible.

setMinScale(scale)

Set the minimum scale for the layer. (Added at v3.1)
Parameters:
<Number> scale Required The minimum scale at which the layer is visible.

setOpacity(opacity)

Initial opacity or transparency of layer. Not supported in Internet Explorer.
Parameters:
<Number> opacity Required Value from 0 to 1, where 0 is 100% transparent and 1 has no transparency. The default value is 1.

setRefreshInterval(interval)

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)
Return type: Layer
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.

setRenderer(renderer)

Sets the renderer for the graphics layer.
Parameters:
<Renderer> renderer Required The renderer used for the graphic.

setScaleRange(minScale, maxScale)

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.

setVisibility(isVisible)

Sets the visibility of the layer. When true, the layer is visible.
Parameters:
<Boolean> isVisible Required Set the visibility of the layer.

show()

Sets the visibility of the layer to "true".

suspend()

Suspends layer drawing. (Added at v3.1)
Event Details
[ On Style Events | Connect Style Event ]

click

Fires when a graphic has been clicked. Should be used in favor of onClick. (Added at v3.5)
Event Object Properties:
<Object> event The returned object contains screenPoint, mapPoint, and Graphic.

dbl-click

Fires when a graphic has been double clicked. Should be used in favor of onDblClick. (Added at v3.5)

error

Fires when there is a problem retrieving a layer. Should be used in favor of onError. (Added at v3.5)
Event Object Properties:
<Error> error ArcGIS Server error message returned in a JavaScript error object.

graphic-add

Fires when a graphic is added to the GraphicsLayer. Should be used in favor of onGraphicAdd. (Added at v3.5)
Event Object Properties:
<Graphic> graphic The added graphic.

graphic-draw

Fires when a graphic is drawn. A graphic is drawn or redrawn when:
  • When it is added to the layer.
  • When Geometry or Symbol is modified.
  • When it enters the viewport and intersects the map extent.
  • When the layer is redrawn.
(Added at v3.7)
Event Object Properties:
<Graphic> graphic Graphic being drawn. When the layer surfaceType is "svg" or "vml", the graphic's DOM node is accessible with graphic.getNode().

graphic-node-add

Fires when a graphic's DOM node is created and added to the layer. Fires only when the layer surfaceType is "svg" or "vml". (Added at v3.7)
Event Object Properties:
<Graphic> graphic Graphic being drawn.
<HTMLElement> node Graphic's DOM node.

graphic-node-remove

This event is fired when a graphic's DOM node is removed (consider the node destroyed). The DOM node of a graphic is removed when:
  • Graphic is removed from the layer.
  • Graphic exits the viewport on map navigation.
  • When a symbol change cannot be applied to the Graphic without replacing the current node with a new one. For example: when a marker symbol is changed from SimpleMarkerSymbol to PictureMarkerSymbol, onGraphicNodeRemove will be fired for the node that is being replaced (SVG Circle) and onGraphicNodeAdd will be fired for the new node (SVG Image).
Fires only when the layer surfaceType is "svg" or "vml". (Added at v3.7)
Event Object Properties:
<Graphic> graphic Graphic being drawn.
<HTMLElement> node Graphic's DOM node.

graphic-remove

Fires when a graphic is removed from the GraphicsLayer. Should be used in favor of onGraphicRemove. (Added at v3.5)
Event Object Properties:
<Graphic> graphic The removed graphic.

graphics-clear

Fires when all graphics in the GraphicsLayer are cleared. Should be used in favor of onGraphicsClear. (Added at v3.5)

load

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.

mouse-down

Fires when a mouse button is pressed down and the mouse cursor is on a graphic. Should be used in favor of onMouseDown. (Added at v3.5)
Event Object:
<MouseEvent> mouseEvent A standard DOM MouseEvent with additional properties mapPoint and screenPoint.

mouse-drag

Fires while the mouse is being dragged until the mouse button is released. Should be used in favor of onMouseDrag. (Added at v3.5)
Event Object:
<MouseEvent> mouseEvent A standard DOM MouseEvent with additional properties mapPoint and screenPoint.

mouse-move

Fires as the mouse moves through a graphic on the GraphicsLayer. Should be used in favor of onMouseMove. (Added at v3.5)
Event Object:
<MouseEvent> mouseEvent A standard DOM MouseEvent with additional properties mapPoint and screenPoint.

mouse-out

Fires as the mouse exits a graphic on the GraphicsLayer. Should be used in favor of onMouseOut. (Added at v3.5)
Event Object:
<MouseEvent> mouseEvent A standard DOM MouseEvent with additional properties mapPoint and screenPoint.

mouse-over

Fires when the mouse first enters into a graphic on the GraphicsLayer. Should be used in favor of onMouseOver. (Added at v3.5)
Event Object:
<MouseEvent> mouseEvent A standard DOM MouseEvent with additional properties mapPoint and screenPoint.

mouse-up

Fires when a mouse button is released and the mouse cursor is on a graphic. Should be used in favor of onMouseUp. (Added at v3.5)
Event Object:
<MouseEvent> mouseEvent A standard DOM MouseEvent with additional properties mapPoint and screenPoint.

opacity-change

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.

refresh-interval-change

This event is fired when the layer's refreshInterval is modified. (Added at v3.7)

resume

Fires when a layer resumes drawing. Should be used in favor of onResume. (Added at v3.5)

scale-range-change

Fires when a layer's minScale and/or maxScale is changed. Should be used in favor of onScaleRangeChange. (Added at v3.5)

scale-visibility-change

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)

suspend

Fires when a layer suspends drawing. Should be used in favor of onSuspend. (Added at v3.5)

update

Fires any time a layer has finished loading or updating itself. For an ArcGISTiledMapServiceLayer, the event fires when all required tiles have been retrieved and displayed. For an ArcGISDynamicMapServiceLayer or ArcGISImageServiceLayer, the event fires when the map image has been retrieved and displayed. For a GraphicsLayer, the event fires when all graphics have been redrawn after a pan or zoom. Deprecated at v2.0. Use update-start and update-end instead. (Added at v3.6)

update-end

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.

update-start

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)

visibility-change

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.
Show Modal