polarmap
Version:
Leaflet library for polar map projection switching
259 lines (190 loc) • 9.72 kB
Markdown
# API
PolarMap.js contains two parts: the lower-level Leaflet.PolarMap plugin and the basic PolarMap library.
This document will explain the capabilities of the Leaflet.PolarMap and PolarMap APIs.
## PolarMap
Initializing a map with the basic PolarMap library is simple. Once the document is loaded (using JQuery or body `onload`), initialize PolarMap with the container element's ID.
```html
<!-- index.html -->
<div id='mapContainer'></div>
```
```javascript
// app.js
var map = PolarMap('mapContainer');
```
That is all. PolarMap will create a Leaflet map in the element, with the following features enabled:
* Support for Arctic Connect projections EPSG:3571–3576 in a layer switching control
* Controls for rotating the maps through available projections
* Support for permalinks in the browser URL location
Additionally, the `PolarMap` function can accept an options object.
### PolarMap Options
* key: `geosearch`
* value: `true` or `false`
* default value: `false`
* Adds a map control for geospatial location search. Requires the [L.GeoSearch plugin](https://github.com/smeijer/L.GeoSearch) to be included in the page along with a provider before it will work.
* key: `locate`
* value: `true` or `false`
* default value: `false`
* After the map is loaded, the user location will be automatically detected using the W3C GeoLocation API. PolarMap will then automatically switch to the projection closest to the user's longitude.
* key: `permalink`
* value: `true` or `false`
* default value: `true`
* Will save the user's current projection, latitude and longitude, and zoom level in the page's URL. Will automatically update on map pan/zoom or projection change.
These options can only be changed when the `PolarMap` function is first called.
Aside from specifying custom initialization options, the returned object (`map`) exposes methods for map customization.
### PolarMap Methods
* method: `addLayer`
* arguments: [Leaflet LayerGroup](http://leafletjs.com/reference.html#layergroup), `Options` object
* `Options` object
* key: `name`
* value: Name for layer, if added to layer switch control.
* key: `switcher`
* value: `true` or `false`
* default value: `false`
* If true, will display the layer in the PolarMap Layer switching map control.
* method: `getBaseLayer`
* arguments: none
* description: Returns the base tile layer currently used on the map
## Leaflet.PolarMap
The base classes in Leaflet.PolarMap:
* `L.PolarMap.Map`
* `L.PolarMap.TileLayer`
* `L.PolarMap.LAEATileLayer`
* `L.PolarMap.Control.Rotation`
* `L.PolarMap.Util.Hash`
### `L.PolarMap.Map`
Very similar to `L.Map`, with a few differences. Instead of initializing with an array for `layers`, pass an `L.PolarMap.TileLayer` to `baseLayer`.
```javascript
var map = L.PolarMap.map('map_container', {
baseLayer: L.PolarMap.tileLayer(…)
});
```
`L.PolarMap.Map` also supports the other [options for L.Map](http://leafletjs.com/reference.html#map-options), aside from `crs` and `layers`.
#### L.PolarMap.Map.loadTileProjection()
This method can be used to dynamically update the map with a new tile layer, even if the tile layer has a different projection.
```javascript
map.loadTileProjection(L.PolarMap.tileLayer(…))
```
The object loaded in must be at least an `L.TileLayer` object. It is recommended it also defines the options set in `L.PolarMap.TileLayer` and `L.PolarMap.LAEATileLayer`.
### `L.PolarMap.TileLayer`
A subclass of `L.TileLayer`. Should be initialized with additional options to define the tile layer's CRS and custom parameters. Be sure to define the projection in Proj4JS first.
```javascript
// See L.TileLayer documentation for URL template
var url = "http://{s}.tiles.arcticconnect.ca/osm_3571/{z}/{x}/{y}.png";
// Extent is dependent on projection. The following is used for EPSG:3571 to
// EPSG:3576.
var extent = 11000000 + 9036842.762 + 667;
var tileLayer = L.PolarMap.tileLayer(url, {
// Name is required for storing the layer id in the permalink if the
// PolarMap permalink module is active.
name: "ac_3571",
// CRS for the tile layer.
crs: "EPSG:3571",
// Minimum/maximum zoom level for the tile provider.
minZoom: 0,
maxZoom: 18,
// Is the tile layer provided by a TMS? FYI: OSM is not a TMS.
tms: false,
// The tile origin for the projection. LAEA is based on the extent, may
// vary for other projection systems.
origin: [-extent, extent],
// The tile resolution at the lowest zoom level. May vary for other
// projection systems.
maxResolution: ((extent - -extent) / 256),
// The bounds for the tile layer projection. Will cause Leaflet to avoid
// loading tiles outside these bounds. May vary for other projection
// systems.
projectedBounds: L.bounds(L.point(-extent, extent),L.point(extent, -extent)),
// Whether the World map should be drawn continuously. May not make
// sense to use for certain projections.
continuousWorld: false,
// Whether to wrap tiles. May not make sense to use for certain
// projections.
noWrap: true,
// Attribution for the tile layer. This is required for certain tile
// providers.
attribution: 'Map © <a href="http://arcticconnect.ca">ArcticConnect</a>. Data © <a href="http://osm.org/copyright">OpenStreetMap</a> contributors',
// If the tile layer is part of a set of projections that form a
// complete circle, then prev/next can link to the next CCW/CW layer in
// the series when using the L.PolarMap.Control.Rotation module.
// Can be omitted if the module is not in use.
prev: L.PolarMap.tileLayer(…),
next: L.PolarMap.tileLayer(…)
});
```
The class does not enforce any defaults required for `L.PolarMap.Map`, but may in the future.
### `L.PolarMap.LAEATileLayer`
A subclass of `L.PolarMap.TileLayer`. Has presets for an LAEA projection already set in the options. You will be required to initialize with the URL string and include `name`, `crs`, and optionally `proj4def` in the `options` hash.
A set of LAEA Tile Layer objects have been preset with Arctic Connect tile layers for LAEA projections 3571–3576.
* `L.PolarMap.layer3571`
* `L.PolarMap.layer3572`
* `L.PolarMap.layer3573`
* `L.PolarMap.layer3574`
* `L.PolarMap.layer3575`
* `L.PolarMap.layer3576`
They do not need to be called as a function as they are already initialized.
### `L.PolarMap.Control.Rotation`
A map control that adds two buttons: one to rotate the map clockwise, the other to rotate counter-clockwise. Requires custom glue code to determine which tile layer to switch to on button press.
```javascript
var tiles = {
"id_1": L.PolarMap.tileLayer(…),
"id_2": L.PolarMap.tileLayer(…)
};
var map = L.PolarMap.map('map_container', {
baseLayer: tiles["id_1"]
});
var getBaseLayer: function () {
var foundLayer = null;
for (var layerName in tiles) {
if (tiles.hasOwnProperty(layerName)) {
if (map.hasLayer(tiles[layerName])) {
foundLayer = tiles[layerName];
}
}
}
return foundLayer;
};
var rotationControls = L.PolarMap.Control.rotation({
onRotateCW: function() {
map.loadTileProjection(getBaseLayer().next);
},
onRotateCCW: function() {
map.loadTileProjection(getBaseLayer().prev);
}
});
rotationControls.addTo(map);
```
Assuming a map has been created using a Tile Layer with `prev` and `next` defined, then rotation controls can be used to switch between the tile layers. Note that a way to find the tile layers is required (see the `getBaseLayer` function) that can specifically get the base layer from the `L.PolarMap.Map` object; the map object does not provide such a function at this time.
### `L.PolarMap.Util.Hash`
Very similar to the [Leaflet Hash plugin](https://github.com/mlevans/leaflet-hash), it works identically except provides support for setting the base layer in addition to the latitude/longitude/zoom level. To do this, the `getBaseLayer` and `setBaseLayer` options must be set in the constructor.
```javascript
var getBaseLayer: function () {
var foundLayer = null;
for (var layerName in tiles) {
if (tiles.hasOwnProperty(layerName)) {
if (map.hasLayer(tiles[layerName])) {
foundLayer = tiles[layerName];
}
}
}
return foundLayer;
};
var setBaseLayer: function (name) {
for (var layerName in tiles) {
if (tiles.hasOwnProperty(layerName)) {
if (tiles[layerName].options.name === name) {
map.loadTileProjection(tiles[layerName]);
}
}
}
};
L.PolarMap.Util.hash(map, {
getBaseLayer: function () {
return getBaseLayer().options.name;
},
setBaseLayer: function (name) {
setBaseLayer(name);
}
});
```
Note that glue code for determining the base layer is required.
Once instantiated, the permalink code is activated and will track the map pans and zooms. When loading a URL with the projection, latitude, longitude, and zoom level in the params then these values will override any defaults set for the map object.