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

require(["esri/layers/WMSLayer"], function(WMSLayer) { /* code goes here */ });

Description

(Added at v2.1)
A layer for OGC Web Map Services (WMS). If the first layer added to the map is a WMS layer, the map will use the spatial reference of this layer. The default behavior of a WMSLayer is to execute a WMS GetCapabilities request, which requires using a proxy page. See the Using the proxy page help topic for more details. An alternate approach is to pass a resourceInfo object into the constructor which does not require a GetCapabilities request.

Note:
  • The WMSLayer does not support using Styled Layer Descriptor (SLD) documents.
  • A thin gap line is visible where the dateline is located.
  • The images may flash when the display transitions from one world to two, or vice versa.

Samples

Search for samples that use this class.

Class hierarchy

esri/layers/Layer
|_esri/layers/DynamicMapServiceLayer
  |_esri/layers/WMSLayer

Constructors

NameSummary
new WMSLayer(url, options?)Creates a new WMSLayer object.

Properties

NameTypeSummary
allExtentsExtent[]All bounding boxes defined for the layer.
classNameStringclass attribute of the layer's node.
copyrightStringCopyright of the WMS service.
customLayerParametersObjectUse this to append different custom parameters to WMS layer requests.
customParametersObjectUse this to append custom parameters to all WMS requests.
descriptionStringDescription of the WMS service.
extentExtentExtent of the WMS service.
featureInfoFormatStringFeature info MIME type to request.
fullExtentExtentFull extent as defined by the map service.
getFeatureInfoURLStringThe URL for the WMS GetFeatureInfo call.
getMapURLStringThe URL for the WMS GetMap call.
idStringID assigned to the layer.
imageFormatStringThe map image format.
initialExtentExtentInitial extent as defined by the map service.
layerInfosWMSLayerInfo[]List of layers in the WMS service.
loadErrorErrorSet if the layer failed to load.
loadedBooleanWhen the layer is loaded, the value becomes "true", and layer properties can be accessed.
maxHeightNumberMaximum height in pixels the WMS service supports.
maxScaleNumberMaximum visible scale for the layer.
maxWidthNumberMaximum width in pixels the WMS service supports.
minScaleNumberMinimum visible scale for the layer.
opacityNumberOpacity or transparency of layer.
refreshIntervalNumberRefresh interval of the layer in minutes.
showAttributionBooleanWhen true, the layer's attribution is displayed on the map.
spatialReferenceSpatialReferenceSpatial reference of the WMS service.
spatialReferencesNumber[]An array of WKIDs of all spatial references defined for the layer.
suspendedBooleanWhen true, the layer is suspended.
titleStringTitle of the WMS service.
urlStringURL to the ArcGIS Server REST resource that represents a map service.
versionStringVersion of the WMS service.
visibleBooleanVisibility of the layer.
visibleAtMapScaleBooleanWhen true, the layer is visible at the current map scale.
visibleLayersString[]A list of layer names that represent the layers to include in the exported map.

Methods

NameReturn typeSummary
attr(name, value)LayerAdds a new attribute or changes the value of an existing attribute on the layer's node.
getImageFormat()StringReturns the current map image format.
getImageUrl(extent, width, height, callback)StringMethod to implement when extending DynamicMapServiceLayer.
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.
refresh()NoneRefreshes the map by making a new request to the server.
resume()NoneResumes layer drawing.
setCustomParameters(customParameters, customLayerParameters?)NoneSets the custom parameters used on the WMS layer.
setImageFormat(format)NoneSet the map image format; valid values are "png", "jpg", "pdf", "bmp", "gif" and "svg".
setImageTransparency(transparency)NoneSpecify whether the background image is transparent.
setMaxScale(scale)NoneSet the maximum scale for the layer.
setMinScale(scale)NoneSet the minimum scale for the layer.
setOpacity(opacity)NoneSets the opacity of the layer.
setRefreshInterval(interval)LayerChanges the layer's refresh interval to the given value (in minutes).
setScaleRange(minScale, maxScale)NoneSet the scale range for the layer.
setVisibility(isVisible)NoneSets the visibility of the layer.
setVisibleLayers(layers)NoneSpecify a list of layer names to updates the visible layers.
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
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.
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 WMSLayer(url, options?)

Creates a new WMSLayer object.
Parameters:
<String> url Required URL to the OGC Web Map Service. An example is http://sampleserver1.arcgisonline.com/ArcGIS/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/WMSServer. As of version 3.10, if a version is included in the service URL it is honored for a GetCapabilities request. If options.version is specified it is honored for the GetCapabilities request and overrides a version included in the service URL.
<Object> options Optional Optional parameters. See options list.
options properties:
<Object> customLayerParameters Optional The customLayerParameters object used for the WMS Layer.
NOTE: If this is also set within the constructor's resourceInfo, the parameters within the resourceInfo take precedence.
<Object> customParameters Optional The customParameters object used for the WMS Layer.
NOTE: If this is also set within the constructor's resourceInfo, the parameters within the resourceInfo take precedence.
<String> format Optional Specify the map image format, valid options are png,jpg,bmp,gif,svg.
<Object> resourceInfo Optional An optional resourceInfo object. The default behavior of the WMSLayer is to execute a WMS GetCapabilities request which requires using a proxy page. When a resourceInfo object is specified the GetCapabilities request is not executed. See the object specifications table below for the structure of the resourceInfo object.
require([
  "esri/layers/WMSLayerInfo", "esri/geometry/Extent", ... 
], function(WMSLayerInfo, Extent, ... ) {
  var layer1 = new WMSLayerInfo({name:"1",title:"Rivers"});
  var layer2 = new WMSLayerInfo({name:"2",title:"Cities"});
  var resourceInfo = {
    extent: new Extent(-126.40869140625,31.025390625,-109.66552734375,41.5283203125,{wkid: 4326}),
    layerInfos: [layer1, layer2]
  };
  ...
});
<Boolean> transparent Optional If the WMS service supports transparency, specify whether the image background is transparent.
<String> version Optional A version number. Supported versions are: "1.1.0","1.1.1" and "1.3.0".

If no version is specified in the constructor options it will use the version provided in the WMS URL VERSION parameter. If no version is provided via the WMS URL or the constructor options it will use the version the WMS service returns in a capabilities response, normally the latest version. Added at v3.10
<String[]> visibleLayers Optional A list of layer names that represent the layers to include in the exported map. By default no layers are visible. The order of layers in the list defines the order the layers will display in the map.
Object Specifications:
<resourceInfo>
<String> copyright Optional The copyright of the WMS Service.
<Object> customLayerParameters Required Use this to append different custom parameters to WMS layer requests. For example, if your WMS layer supports styles, styles can be used as a custom parameter for layer requests.
"customLayerParameters" : {
  "styles": "pointsymbolizer", 
  "SLD": "https://.../point_pointSymbolizer.xml"
}
The custom parameters are applied to GetMap and GetFeatureInfo.
NOTE: customLayerParameters can be part of resourceInfo or outside of it in the WMSLayer's constructor. If it is set in resourceInfo and also directly as customLayerParameters in the constructor, the one in resourceInfo takes precedence.
<Object> customParameters Required Use this to append custom parameters to all WMS requests. If an access key is required, the key can be configured as a custom parameter.
"customParameters" : {"key": "1R-ADNF-6NCD"}
The custom parameters are applied to GetCapabilities, GetMap, and GetFeatureInfo.
NOTE: customParameters can be part of resourceInfo or outside of it in the WMSLayer's constructor. If both are set in resourceInfo and also directly as customParameters in the constructor, the one in resourceInfo takes precedence.
<String> description Optional The description of the WMS service.
<Extent> extent Required Extent of the WMS service. The extent must be specified in the spatial reference of the service. Required.
<String> featureInfoFormat Optional Feature info MIME type to request. For example, text/html or text/plain.
<String> getFeatureInfoURL Optional URL to getFeatureInfo endpoint.
<String> getMapURL Required The URL for the GetMap request. Required if the URL for the GetCapabilities is different than the URL for GetMap.
<WMSLayerInfo> layerInfos Required An array of WMSLayerInfo, each WMSLayerInfo object must have the name property. Required.
<Number> maxHeight Optional The maximum height, in pixels, of the WMS service.
<Number> maxScale Optional The maximum scale value. When zoomed out farther than this scale the layer will display.
<Number> maxWidth Optional The maximum width, in pixels, of the WMS service.
<Number> minScale Optional The minimum scale value. When zoomed in closer than this scale the layer will display.
<String> title Optional The title of the WMS service.
<String> version Optional Version of the WMS service. The default value is "1.3.0". Supported versions are "1.1.0", "1.1.1", "1.3.0".
Sample:

This snippet requires setting up a proxy page

require([
  "esri/layers/WMSLayer", ... 
], function(WMSLayer, ... ) {
  var wmsLayer = new WMSLayer(wmsURL); 
  ...
});

This snippet specifies the resourceInfo option which does not require proxy page.

require(["esri/map", "esri/geometry/Extent", "esri/layers/WMSLayer", 
  "esri/layers/WMSLayerInfo", "dojo/domReady!"], 
  function (Map, Extent, WMSLayer, WMSLayerInfo){
    var map = new Map("map", {
      basemap: "streets",
      center: [21.84, -2.84],
      zoom: 5
    });

    var wmsLayer = new WMSLayer("http://host/geoserver/wms", {
      format: "png",
      resourceInfo: {
        copyright: "GeoServer",
        description: "Africa Wind Data",
        extent: new Extent(-180, -90, 180, 90, {wkid: 4326}),
        featureInfoFormat: "text/html",
        getFeatureInfoURL: "http://host/geoserver/ows",
        getMapURL: "http://host/geoserver/ows",
        layerInfos: [
          new WMSLayerInfo({
            name: "AFG_Wind:AFG_WindGenAnnualEnergy",
            title: "Mean annual generalized wind power density",
            queryable: true,
            showPopup: true
          })
        ],
        spatialReferences: [3857, ..., 42303],
        version: "1.3.0"
      },
      version: "1.3.0",
      visibleLayers: [
        "AFG_Wind:AFG_WindGenAnnualEnergy"
      ]
    });

    wmsLayer.on("error", function (response){
      console.log("Error: %s", response.error.message);
    });
    map.addLayer(wmsLayer);
  });
Property Details

<Extent[]> allExtents

All bounding boxes defined for the layer. (Added at v3.13)

<String> className

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

<String> copyright

Copyright of the WMS service. This is the value of the AccessConstraints capabilities property.

<Object> customLayerParameters

Use this to append different custom parameters to WMS layer requests. For example, if your WMS layer supports styles, styles can be used as a custom parameter for layer requests.
The custom parameters are applied to GetMap and GetFeatureInfo.

NOTE: customLayerParameters can be part of resourceInfo or outside of it in the WMSLayer's constructor. If both are set in resourceInfo and also directly as customLayerParameters in the constructor, the one in resourceInfo takes precedence. (Added at v3.18)
Sample:
"customLayerParameters" : {
  "styles": "pointsymbolizer", 
  "SLD": "https://.../point_pointSymbolizer.xml"
}

<Object> customParameters

Use this to append custom parameters to all WMS requests. If an access key is required, the key can be configured as a custom parameter. The custom parameters are applied to GetCapabilities, GetMap, and GetFeatureInfo.

NOTE: customParameters can be part of resourceInfo or outside of it in the WMSLayer's constructor. If it is set in resourceInfo and also directly as customParameters in the constructor, the one in resourceInfo takes precedence. (Added at v3.18)
Sample:
"customParameters" : {"key": "1R-ADNF-6NCD"}

<String> description

Description of the WMS service. This is the value of the Abstract capabilities property.

<Extent> extent

Extent of the WMS service.

<String> featureInfoFormat

Feature info MIME type to request. For example, text/html or text/plain. (Added at v3.17)
Known values: text/html | text/plain

<Extent> fullExtent

Full extent as defined by the map service.

<String> getFeatureInfoURL

The URL for the WMS GetFeatureInfo call. (Added at v3.17)

<String> getMapURL

The URL for the WMS GetMap call.

<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.
    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);
      }
    }
    

<String> imageFormat

The map image format.

<Extent> initialExtent

Initial extent as defined by the map service.

<WMSLayerInfo[]> layerInfos

List of layers in the WMS service.
Sample:
require([
  "dojo/_base/array", ...
], function(array, ... ){
  array.forEach(wmsLayer.layerInfos, function(layerInfo) {
    console.log(layerInfo.title);
  });
});

<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> maxHeight

Maximum height in pixels the WMS service supports.

<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> maxWidth

Maximum width in pixels the WMS service supports.

<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)

<Boolean> showAttribution

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

<SpatialReference> spatialReference

Spatial reference of the WMS service.

<Number[]> spatialReferences

An array of WKIDs of all spatial references defined for the layer. (Added at v3.13)

<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> title

Title of the WMS service.

<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:
http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer. (Added at v1.2)

<String> version

Version of the WMS service. Supported versions are: 1.1.0,1.1.1 and 1.3.0.

<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

<String[]> visibleLayers

A list of layer names that represent the layers to include in the exported map. By default no layers are visible. The order of layers in the list defines the order the layers will display in the map. (Added at v3.16)
Method Details

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.

getImageFormat()

Returns the current map image format. (Added at v3.16)
Return type: String

getImageUrl(extent, width, height, callback)

Method to implement when extending DynamicMapServiceLayer. For more details, see Creating custom layer types. (Added at v1.3)
Return type: String
Parameters:
<Extent> extent Required Current extent of the map.
<Number> width Required Current width of the map in pixels.
<Number> height Required Current height of the map in pixels.
<Function> callback Required The function to call when the method has completed.

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.

refresh()

Refreshes the map by making a new request to the server. In order to refresh the layer in this manner, setDisableClientCaching must be true. This ensures that map images are not cached on the client. (Added at v1.2)

resume()

Resumes layer drawing. (Added at v3.1)

setCustomParameters(customParameters, customLayerParameters?)

Sets the custom parameters used on the WMS layer. If customParameters is used, it applies for all requests to the WMS service, whereas customLayerParameters is used only for map requests. If both are set, customLayerParameters takes precedence.

NOTE: This will update the properties and refresh the layer. In addition, if one of the inputs is empty it will overwrite it as not being set. (Added at v3.18)
Parameters:
<Object> customParameters Required The customParameters object used append WMS requests.
<Object> customLayerParameters Optional The customLayerParameters object used append specific WMS layer requests.

setImageFormat(format)

Set the map image format; valid values are "png", "jpg", "pdf", "bmp", "gif" and "svg".
Parameters:
<String> format Required The image format.
Sample:
wmsLayer.setImageFormat("jpg");

setImageTransparency(transparency)

Specify whether the background image is transparent. Only valid if the WMS service supports transparency.
Parameters:
<Boolean> transparency Required When true the background image is transparent.
Sample:

wmsLayer.setImageTransparency(true);

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)

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);

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.

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.

setVisibleLayers(layers)

Specify a list of layer names to updates the visible layers.
Parameters:
<String[]> layers Required An array of layer ids.
Sample:

wmsLayer.setVisibleLayers(["0","1"]);

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 ]

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.

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.

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