layer

Extends dispatch.

---

po.layer(l[, u])

Constructs a new layer with the specified load function l, and optional unload function u. The layer constructor is not used directly unless implementing a custom layer; see the image and geoJson layers for reference implementations.

The load function is used by the tile cache to create the tile element. It is invoked with two arguments: the tile object and a tile projection constructor. Use of the tile projection is optional.

Tile objects are a superset of coordinates; they have the standard row, column and zoom number attributes. The tile’s key attribute is an unique string based on the coordinate: “{Z}/{X}/{Y}”. The load function is responsible for populating the element attribute with an SVG element (such as a g or image element) that can be added to the layer container.

Tile projections are passed to the load function as a constructor. The constructor must be invoked, passing in the tile object, to construct the projection. Once constructed, the projection has a single attribute, locationPoint which has similar semantics to the map’s locationPoint method. However, the returned points are relative to the top-left corner of the tile (rather than the map), allowing the layer to reposition tiles without reprojecting.

Asynchronously-loaded tiles present some additional requirements.

Load functions are responsible for setting the ready attribute of the tile to true when the tile is ready to be displayed. This avoids displaying tiles progressively as they load (for example, with images); the layer takes care of displaying cached “proxy” tiles at neighboring zoom levels while tiles are loading.

When the tile is ready, the load function must dispatch a load event on the layer. The load event must have a type string attribute with the value “load”, and a tile attribute referencing the tile object. The layer requires this load event in order to hide any proxy tiles that were displayed while the tile was loading.

If tiles are loaded asynchronously, the load function should store the request object returned by the queue on the request attribute. This allows the cache to cancel pending requests if necessary, such as when a tile with a queued request is no longer needed.

The unload function u should be implemented if tiles are loaded asynchronously, so as to abort the tile request. This method is invoked with a single argument of the tile object on tiles that are removed from the cache.

layer.container()

Returns the layer’s container element. The container is an SVG g element with the class attribute “layer”.

The container initially has seven child g elements that correspond to the tiles at various zoom levels relative to the map’s (rounded) zoom level. When all needed tiles are loaded, the proxy tiles are removed from the map and only the last g element contains tiles. These group elements have class attributes to allow zoom-dependent styling. This includes both relative zoom classes, such as “zoom-1” and “zoom+1”, and absolute zoom classes, such as “zoom9” and “zoom13”.

The layer container, the zoom-specific group elements, and the tiles themselves have transform attributes to control how tiles are displayed. Tiles are translated relative to the map center. The zoom-specific group elements then provide relative scaling (e.g., scale(2) for the -1 zoom layer). Lastly, the layer container is translated such that the origin is the center of the map’s viewport, with additional transformation as needed to support rotation, continuous zooming, and layer-specific affine transforms.

layer.id([x])

Sets or gets the id attribute on the layer’s container. If the argument x is specified, it is a unique string identifier for the layer, and this method returns this. If no arguments are specified, this method returns the current id. The id defaults to null, which means that no id attribute should be set on the container.

layer.map([x])

Adds this layer to the specified map x, removes this layer from its current map, or returns the current map. This method is typically not called directly, but is needed to support the map’s add and remove methods.

If the argument x is specified, this method returns this. If x is null, this layer is removed from its current map; otherwise, this layer is added to the specified map. If no arguments are specified, this method returns the current map, which may be null. Whew!

View

layer.tile([x])

Sets or gets whether this layer is tiled. If the boolean argument x is specified, the method enables or disables tiling accordingly, and returns this. If no arguments are specified, the method returns true if and only if this layer is tiled.

Layers are tiled by default. Disabling tiling is useful if the associated data (say a static GeoJSON file) is not tiled, and thus you only want to display the data once.

layer.transform([x])

Sets or gets the layer’s affine transform. If the argument x is specified, it sets the transform and returns this. If no arguments are specified, it returns the current transform, which defaults to null. The identity transform and null are equivalent.

layer.visible([x])

Sets or gets whether the layer is visible. If the boolean argument x is specified, the method sets the visibility and returns this. If no arguments are specified, the method returns true if and only if this layer is visible.

Layers are visible by default. Invisible layers are useful for toggling visibility without changing z-order. Tiles for invisible layers are not loaded.

layer.zoom([x])

Sets or gets the layer zoom transform. If the argument x is specified, the method sets the zoom transform using the given zoom transform function. If x is a constant, it is wrapped in a function that returns x. If no arguments are specified, the method returns the zoom transform function, which defaults to null.

Zoom transform functions allow the layer to serve tiles at a different level from the map. For example, a layer might only have tiles at zoom level 4, and so set the zoom transform to the constant 4. Alternatively, a layer might using a min-max function to bound the set of available zoom levels: function(z) { return Math.max(4, Math.min(8, z)); }.

If the transformed zoom level is too far from the map’s zoom level, no tiles may be displayed. Currently, the transformed zoom level delta may be up to +2 and down to -4.

Events

Layers use the dispatch mechanism to notify interested parties of events. Layers currently support only the “load” event.

layer.show(t)

This method may be implemented by subclasses to be notified immediately before a tile is displayed. This method is passed the tile t that is newly visible. For example, the geoJson uses this to dispatch the show event, which then allows users to customize the appearance of visible tiles before they are displayed.

layer.reload()

Clears the cache, re-requests any currently-visible tiles, and returns this. This method is used internally by some layer implementations; for example, when the URL template of an image layer is changed. This method may be called directly to clear the cache and force a reload of the tiles. Note that this method does not clear the browser cache, and thus tiles may not be re-fetched from the server.

layer.cache

A reference to layer’s tile cache.