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

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

Description

(Added at v3.2)
The WebTiledLayer class provides a simple way to add non-ArcGIS Server map tiles as a layer to a map. The constructor takes a URL template that usually follows a pattern of https://some.domain.com/${level}/${col}/${row}/ where level corresponds to a zoom level, and column and row represent tile column and row, respectively. This pattern is not required, but is the most common one on the web currently. As of version 3.34, the pattern can also be specified as https://some.domain.com/${z}/${y}/${x}/.

The constructor also takes an options object. The subDomains property can be used to specify subDomains where tiles are served to speed up tile retrieval (using subDomains gets around the browser limit of the max number of concurrent requests to a domain). If subDomains are specified, the urlTemplate should include a ${subDomain} place holder. The options object also accepts a copyright property that can be used to define attribution information that will be displayed in the map's Attribution widget. For additional information on working with attribution please visit the official attribution in your app documentation.

Samples

Search for samples that use this class.

Class hierarchy

esri/layers/Layer
|_esri/layers/TiledMapServiceLayer
  |_esri/layers/WebTiledLayer

Constructors

NameSummary
new WebTiledLayer(urlTemplate, options?)Creates a new WebTiledLayer.

Properties

NameTypeSummary
attributionDataUrlStringThe URL, when available, where the layer's attribution data is stored.
classNameStringclass attribute of the layer's node.
copyrightStringThe attribution information for the layer.
credentialCredentialProvides credential information for the layer such as userid and token if the layer represents a resource that is secured with token-based authentication.
fullExtentExtentThe full extent of the layer.
hasAttributionDataBooleanWhen true, the layer has attribution data.
idStringID assigned to the layer.
initialExtentExtentThe initial extent of 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.
showAttributionBooleanWhen true, the layer's attribution is displayed on the map.
spatialReferenceSpatialReferenceThe spatial reference of the layer.
suspendedBooleanWhen true, the layer is suspended.
tileInfoTileInfoDefine the tile info for the layer including lods, rows, cols, origin and spatial reference.
tileServersString[]The tile server names for the layer.
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
attr(name, value)LayerAdds a new attribute or changes the value of an existing attribute on the layer's node.
getAttributionData()DeferredAsynchrously returns custom data for the layer when available.
getMap()MapReturns reference to the map control the layer is added to.
getNode()HTMLElementReturns the layer's DOM node.
getTileUrl(level, row, column)StringMethod to implement when extending TiledMapServiceLayer.
hide()NoneSets the visibility of the layer to "false".
isVisibleAtScale(scale)BooleanReturns true if the layer is visible at the given scale.
refresh()NoneReloads all the tiles in the current view.
resume()NoneResumes layer drawing.
setExclusionAreas()ArraySpecify areas to not show tiles.
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.
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 WebTiledLayer(urlTemplate, options?)

Creates a new WebTiledLayer.
Parameters:
<String> urlTemplate Required The URL template to retrieve the tiles. The URL template follows a pattern of http://some.domain.com/${Z}/${X}/${Y}/ where Z corresponds to a zoom level, and X and Y represent tile column and row, respectively. You can also use the equivalent https://some.domain.com/${level}/${col}/${row}/ pattern.
<Object> options Optional Optional parameters. See options list.
options properties:
<String> copyright Optional Define attribution information for the layer to be used by the Attribution widget.
<Extent> fullExtent Optional Specify the full extent of the layer. If no value is specified the default value, world extent in Web Mercator, is used.
<Extent> initialExtent Optional Specify the initial extent of the layer. If no value is specified the default value, world extent in Web Mercator, is used.
<Boolean> resampling Optional When true, tile resampling is enabled. Default value is false.
<Number> resamplingTolerance Optional Number of levels beyond the last level where tiles are available. If not specified, resampling is enabled at all levels where tiles are not available.
<String[]> subDomains Optional Specify subDomains where tiles are served to speed up tile retrieval (using subDomains gets around the browser limit of the max number of concurrent requests to a domain). If subDomains are specified, the urlTemplate should include a ${subDomain} place holder.
<TileInfo> tileInfo Optional Define the tile info for the layer including lods, rows, cols, origin and spatial reference.
<String[]> tileServers Optional Define additional tile server domains for the layer.
Sample:
require([
  "esri/layers/WebTiledLayer", ... 
], function(WebTiledLayer, ... ) {
  var cycleMap = new WebTiledLayer("http://${subDomain}.tile.opencyclemap.org/cycle/${level}/${col}/${row}.png", {
    "copyright": "Open Cycle Map",
    "id": "Open Cycle Map",
    "subDomains": ["a", "b", "c"]
  });
  ...
});
Property Details

<String> attributionDataUrl

The URL, when available, where the layer's attribution data is stored. (Added at v3.1)

<String> className

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

<String> copyright

The attribution information for the layer.

<Credential> credential

Provides credential information for the layer such as userid and token if the layer represents a resource that is secured with token-based authentication. This value is available after the layer has been loaded i.e. layer.loaded is true. (Added at v2.5)

<Extent> fullExtent

The full extent of the layer.

<Boolean> hasAttributionData

When true, the layer has attribution data. Use the getAttributionData method to retrieve this data as JSON. (Added at v3.1)
Known values: true | false
Default value: false

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

<Extent> initialExtent

The initial extent of the layer.

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

<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

The spatial reference of the layer.

<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

<TileInfo> tileInfo

Define the tile info for the layer including lods, rows, cols, origin and spatial reference. If not set it will assume tiles in the Web Mercator tiling scheme.

<String[]> tileServers

The tile server names for the layer.

<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

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.

getAttributionData()

Asynchrously returns custom data for the layer when available. (Added at v3.1)
Return type: Deferred

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

getTileUrl(level, row, column)

Method to implement when extending TiledMapServiceLayer. For more details, see Creating custom layer types. (Added at v1.3)
Return type: String
Parameters:
<Number> level Required Requested tile's level.
<Number> row Required Requested tile's row.
<Number> column Required Requested tile's column.

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

Reloads all the tiles in the current view. (Added at v1.2)

resume()

Resumes layer drawing. (Added at v3.1)

setExclusionAreas()

Specify areas to not show tiles. See the exclusionAreas constructor option description for specifics as to how exclusionAreas work. (Added at v3.10)
Return type: Array
Sample:
var exclusionAreas = [{
  minScale: 40000,
  maxScale: 9028,
  geometry: new Extent(
    13871520.850500003,
    3910293.086000003,
    14574034.873400003,
    4686306.161399998,
    new SpatialReference(102100)
  )
}];

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.

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