wrld.js

TileLayer

Used to load and display tile layers on the map. Extends GridLayer.

Usage example

L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?{foo}', {foo: 'bar'}).addTo(map);

URL template

A string of the following form:

'http://{s}.somedomain.com/blabla/{z}/{x}/{y}{r}.png'

You can use custom keys in the template, which will be evaluated from TileLayer options, like this:

L.tileLayer('http://{s}.somedomain.com/{foo}/{z}/{x}/{y}.png', {foo: 'bar'});

Creation

Extension methods

Factory Description
L.tilelayer(<String> urlTemplate, <TileLayer options> options?) Instantiates a tile layer object given a URL template and optionally an options object.

Options

Option Type Default Description
minZoom Number 0 Minimum zoom number.
maxZoom Number 18 Maximum zoom number.
maxNativeZoom Number null Maximum zoom number the tile source has available. If it is specified, the tiles on all zoom levels higher than maxNativeZoom will be loaded from maxNativeZoom level and auto-scaled.
subdomains String|String[] 'abc' Subdomains of the tile service. Can be passed in the form of one string (where each letter is a subdomain name) or an array of strings.
errorTileUrl String '' URL to the tile image to show in place of the tile that failed to load.
zoomOffset Number 0 The zoom number used in tile URLs will be offset with this value.
tms Boolean false If true, inverses Y axis numbering for tiles (turn this on for TMS services).
zoomReverse Boolean false If set to true, the zoom number used in tile URLs will be reversed (maxZoom - zoom instead of zoom)
detectRetina Boolean false If true and user is on a retina display, it will request four tiles of half the specified size and a bigger zoom level in place of one to utilize the high resolution.
crossOrigin Boolean false If true, all tiles will have their crossOrigin attribute set to ''. This is needed if you want to access tile pixel data.
Option Type Default Description
tileSize Number|Point 256 Width and height of tiles in the grid. Use a number if width and height are equal, or L.point(width, height) otherwise.
opacity Number 1.0 Opacity of the tiles. Can be used in the createTile() function.
updateWhenIdle Boolean depends If false, new tiles are loaded during panning, otherwise only after it (for better performance). true by default on mobile browsers, otherwise false.
updateWhenZooming Boolean true By default, a smooth zoom animation (during a touch zoom or a flyTo()) will update grid layers every integer zoom level. Setting this option to false will update the grid layer only when the smooth animation ends.
updateInterval Number 200 Tiles will not update more than once every updateInterval milliseconds when panning.
attribution String null String to be shown in the attribution control, describes the layer data, e.g. "© OpenStreetMap contributors".
zIndex Number 1 The explicit zIndex of the tile layer.
bounds LatLngBounds undefined If set, tiles will only be loaded inside the set LatLngBounds.
noWrap Boolean false Whether the layer is wrapped around the antimeridian. If true, the GridLayer will only be displayed once at low zoom levels. Has no effect when the map CRS doesn't wrap around.
pane String 'tilePane' Map pane where the grid layer will be added.
className String '' A custom class name to assign to the tile layer. Empty by default.
keepBuffer Number 2 When panning the map, keep this many rows and columns of tiles before unloading them.

Events

Event Data Description
loading Event Fired when the grid layer starts loading tiles.
tileunload TileEvent Fired when a tile is removed (e.g. when a tile goes off the screen).
tileloadstart TileEvent Fired when a tile is requested and starts loading.
tileerror TileErrorEvent Fired when there is an error loading a tile.
tileload TileEvent Fired when a tile loads.
load Event Fired when the grid layer loaded all visible tiles.
Event Data Description
add Event Fired after the layer is added to a map
remove Event Fired after the layer is removed from a map
Event Data Description
popupopen PopupEvent Fired when a popup bound to this layer is opened
popupclose PopupEvent Fired when a popup bound to this layer is closed
Event Data Description
tooltipopen TooltipEvent Fired when a tooltip bound to this layer is opened.
tooltipclose TooltipEvent Fired when a tooltip bound to this layer is closed.

Methods

Method Returns Description
setUrl(<String> url, <Boolean> noRedraw?) this

Updates the layer's URL template and redraws it (unless noRedraw is set to true).

createTile(<Object> coords, <Function> done?) HTMLElement

Called only internally, overrides GridLayer's createTile() to return an <img> HTML element with the appropiate image URL given coords. The done callback is called when the tile has been loaded.

Extension methods

Layers extending TileLayer might reimplement the following method.
Method Returns Description
getTileUrl(<Object> coords) String

Called only internally, returns the URL for a tile given its coordinates. Classes extending TileLayer can override this function to provide custom tile URL naming schemes.

Method Returns Description
bringToFront() this

Brings the tile layer to the top of all tile layers.

bringToBack() this

Brings the tile layer to the bottom of all tile layers.

getAttribution() String

Used by the attribution control, returns the attribution option.

getContainer() HTMLElement

Returns the HTML element that contains the tiles for this layer.

setOpacity(<Number> opacity) this

Changes the opacity of the grid layer.

setZIndex(<Number> zIndex) this

Changes the zIndex of the grid layer.

isLoading() Boolean

Returns true if any tile in the grid layer has not finished loading.

redraw() this

Causes the layer to clear all the tiles and request them again.

getTileSize() Point

Normalizes the tileSize option into a point. Used by the createTile() method.

Method Returns Description
bindPopup(<String|HTMLElement|Function|Popup> content, <Popup options> options?) this

Binds a popup to the layer with the passed content and sets up the neccessary event listeners. If a Function is passed it will receive the layer as the first argument and should return a String or HTMLElement.

unbindPopup() this

Removes the popup previously bound with bindPopup.

openPopup(<LatLng> latlng?) this

Opens the bound popup at the specificed latlng or at the default popup anchor if no latlng is passed.

closePopup() this

Closes the popup bound to this layer if it is open.

togglePopup() this

Opens or closes the popup bound to this layer depending on its current state.

isPopupOpen() boolean

Returns true if the popup bound to this layer is currently open.

setPopupContent(<String|HTMLElement|Popup> content) this

Sets the content of the popup bound to this layer.

getPopup() Popup

Returns the popup bound to this layer.

Method Returns Description
bindTooltip(<String|HTMLElement|Function|Tooltip> content, <Tooltip options> options?) this

Binds a tooltip to the layer with the passed content and sets up the neccessary event listeners. If a Function is passed it will receive the layer as the first argument and should return a String or HTMLElement.

unbindTooltip() this

Removes the tooltip previously bound with bindTooltip.

openTooltip(<LatLng> latlng?) this

Opens the bound tooltip at the specificed latlng or at the default tooltip anchor if no latlng is passed.

closeTooltip() this

Closes the tooltip bound to this layer if it is open.

toggleTooltip() this

Opens or closes the tooltip bound to this layer depending on its current state.

isTooltipOpen() boolean

Returns true if the tooltip bound to this layer is currently open.

setTooltipContent(<String|HTMLElement|Tooltip> content) this

Sets the content of the tooltip bound to this layer.

getTooltip() Tooltip

Returns the tooltip bound to this layer.

Method Returns Description
addTo(<Map> map) this

Adds the layer to the given map

remove() this

Removes the layer from the map it is currently active on.

removeFrom(<Map> map) this

Removes the layer from the given map

getPane(<String> name?) HTMLElement

Returns the HTMLElement representing the named pane on the map. If name is omitted, returns the pane for this layer.

Method Returns Description
on(<String> type, <Function> fn, <Object> context?) this

Adds a listener function (fn) to a particular event type of the object. You can optionally specify the context of the listener (object the this keyword will point to). You can also pass several space-separated types (e.g. 'click dblclick').

on(<Object> eventMap) this

Adds a set of type/listener pairs, e.g. {click: onClick, mousemove: onMouseMove}

off(<String> type, <Function> fn?, <Object> context?) this

Removes a previously added listener function. If no function is specified, it will remove all the listeners of that particular event from the object. Note that if you passed a custom context to on, you must pass the same context to off in order to remove the listener.

off(<Object> eventMap) this

Removes a set of type/listener pairs.

off() this

Removes all listeners to all events on the object.

fire(<String> type, <Object> data?, <Boolean> propagate?) this

Fires an event of the specified type. You can optionally provide an data object — the first argument of the listener function will contain its properties. The event might can optionally be propagated to event parents.

listens(<String> type) Boolean

Returns true if a particular event type has any listeners attached to it.

once() this

Behaves as on(…), except the listener will only get fired once and then removed.

addEventParent(<Evented> obj) this

Adds an event parent - an Evented that will receive propagated events

removeEventParent(<Evented> obj) this

Removes an event parent, so it will stop receiving propagated events

addEventListener() this

Alias to on(…)

removeEventListener() this

Alias to off(…)

clearAllEventListeners() this

Alias to off()

addOneTimeEventListener() this

Alias to once(…)

fireEvent() this

Alias to fire(…)

hasEventListeners() Boolean

Alias to listens(…)

v0.1.1427