Documentation

Modules

Map

Constructor

new Map(id, options)

Object for interacting with a generic map.

Options

  • baseLayer Either a Leaflet.Layer, or the name of one of the supported base layers (currently 'Minimal' and 'WorldImagery'. Default: Minimal
  • center Centre position of the map. Default: -28, 134
  • zoom the initial zoom level. Default: 4
  • maxZoom the maximum allowed zoom level. Default: 20
  • maxAutoZoom the maximum zoom level to automatically zoom to (when zoomToObject = true). Default: 15
  • defaultLayersControl true to use the default layers control, false to use your own. Default: true
  • scrollWheelZoom whether to enable zooming in/out by scrolling the mouse. Default: false
  • fullscreenControl whether to include a full-screen option. Default: true
  • fullscreenControlOptions:
    • position position of the button on the map. Default: topleft
  • drawControl whether to include drawing controls or not. Default: true
  • drawOptions if drawing control is to be included, then specify options to pass to drawing control here.
  • editOptions if edit option in drawing control is enabled, then specify options to pass to edit control here.
  • singleDraw whether to allow more than 1 shape or region to be drawn at a time. This does NOT apply to markers - only layers and other shapes. See also singleMarker and markerOrShapeNotBoth. Default: true
  • singleMarker whether to allow more than 1 marker to be drawn at a time.. Default: true
  • markerZoomToMax whether to allow zoom to maximum permitted level of current base layer
  • markerOrShapeNotBoth whether to allow users to draw both markers and regions/shapes at the same time. Default: true
  • showFitBoundsToggle whether to include a button to toggle between the initial map zoom and the bounds of the data. Default: false
  • useMyLocation whether to include a "Use My Location" button to place a marker on the map at the user's location. Default: true
  • allowSearchLocationByAddress whether to allow the user to search by address to place a marker on the map. Default: true
  • allowSearchRegionByAddress whether to allow the user to search by address to draw a polygon on the map. Default: true
  • geocodeRegionOptions additional configuration options when using the allowSearchRegionByAddress control. Only relevant when allowSearchRegionByAddress = true:
    • pointToCircle true to render any point locations returned by the geocode service as circles. Default: true
    • pointRadiusMeters The radius of the circle to use when pointToCircle = true. Units are in meters. Default: 500
  • zoomToObject whether to automatically fit the map to the bounds of a new object when added. Default: true
  • draggableMarkers whether to allow point markers to be draggable by default. Default: true
  • wmsFeatureUrl the URL to call to fetch features of a WMS layer (e.g. http://spatial-dev.ala.org.au/geoserver/wms/reflect?). The PID will be appended to this URL. Default:
  • wmsLayerUrl the URL to call to retrieve a WMS layer. The PID will be appended to this URL. Default:
  • sleep True to disable mouse wheel zooming once the mouse has been out of the map for a certain time. Clicking in the map re-enables it. Overrides scrollWheelZoom. Default: true
  • sleepTime Time (milliseconds) until the map 'sleeps' up after the mouse moves away from the map. Only relevant if sleep = true. Default: 750
  • hoverToWake True to wake the map up after the mouse has been held over the map for a certain time (wakeTime). Only relevant if sleep = true. Default: true
  • wakeTime Time (milliseconds) until the map wakes up after mouse over. Only relevant if sleep = true and hoverToWake = true. Default: 750
  • sleepNote True to display text over the map when it is sleeping. Only relevant if sleep = true. Default: false
  • sleepOpacity Opacity of the sleep text. Only relevant if sleep = true and sleepNote = true. Default: 0.7
  • wakeMessage Text to display over the map when it is sleeping. Only relevant if sleep = true and sleepNote = true. Default: 'Click or hover to wake'.

Parameters

Name Type Description
id String Unique id of the map container div. Mandatory.
options Object Configuration options for the map. Optional - sensible defaults will be used if not provided. See the list above.

Constants

Name Description
DEFAULT_OPTIONS Default Map options
DEFAULT_POINT_MARKER_OPTIONS Default options for clustered point markers. See http://leafletjs.com/reference.html#path-options for the options: this object overrides the standard Leaflet options with our default values, where they are different.
LAYER_OPTIONS Supported Layer options. The following configuration options are available:
  • markerWithMouseOver - show a marker at the center of the layer, and hide the layer outline until the mouse is moved over the marker. Default: false
  • markerLocation - used with 'markerWithMouseOver' to specify the position of the marker - if not provided, the center of the layer's bounds will be used. Only works with a single feature.
  • popup - text or HTML to display when the layer (or the placeholder marker if markerWithMouseOver = true) is clicked.

Static Methods

Name Description
addButton Adds a button to the map.. E.g. addButton('fa fa-map-marker', function (button, map) { ... }
addClusteredPoints Adds a layer of clustered L.circleMarker to the map. Clustered points are treated the same as other layers/shapes: i.e. they are NOT considered to be 'markers' like those added with the #addMarker function. See http://leafletjs.com/reference.html#path-options for the possible options. Each point object in the points array must have the following structure:
  • lat - the latitude for the point. Mandatory.
  • lng - the longitude for the point. Mandatory.
  • popup - Text or HTML to be used as the popup when the marker is clicked. Optional.
  • options - options object to override specified options for the individual point. Optional.
Will notify all subscribers.
addControl Adds a control widget to the map
addLayer Add a new layer to the map. Will notify all subscribers.
addLayersControl Add a layer selection control to the map. If options#defaultLayersControl = false, then this function can be used to place the layers control in a position other than the default (top right). See http://leafletjs.com/reference.html#control-layers for details.
addMarker Adds a marker at the specified point. Will notify all subscribers.
addPointsOrIcons Adds a layer of points or icons to map. Icons gives the flexibility of adding shape to map. Each point object in the points array must have the following structure:
  • lat - the latitude for the point. Mandatory.
  • lng - the longitude for the point. Mandatory.
  • type - supported values 'point' or 'icon'. point draws a circle and icon renders the provided image. Default 'point'.
  • popup - Text or HTML to be used as the popup when the marker is clicked. Optional.
  • options - options object to override specified options for the individual point. Optional.
Will notify all subscribers.
addWmsLayer Utility method to add a WMS layer to the map. Triggers events draw:drawstart and draw:created, and will notify all subscribers
clearBoundLimits Clears any limits on the map bounds. This will remove the max bounds (from setMaxBounds) and the display bounds (from fitToBoundsOf) if they exist. The map will be reset to the bounds of the current content (as per fitBounds).
clearLayers Remove all drawn layers from the map. This does not remove markers: see self#clearMarkers. Will notify all subscribers.
clearMarkers Remove all markers from the map. This does not remove other layers or shapes: see self#clearLayers. Will notify all subscribers.
countFeatures Retrieve a count of all features (shapes, layers, markers, etc) on the map
destroy Destroy the map and clear all related event listeners
finishLoading Stop the loading spinner on the map. Note: This is done automatically for any direct changes on the map.
fitBounds Zoom and centre the map to fit the bounds of the current feature(s). If there are no features, then the map will be set to the default zoom and centre.
fitToBoundsOf Zoom and centre the map to fit the bounds of the provided GeoJSON object, but do NOT draw the object. Subsequent calls to Reset Map will automatically fit the map to the bounds of this object. The difference between this and setMaxBounds is that setMaxBounds will prevent the user from panning outside the provided bounds, whereas this method will allow that.
getAllMarkers Retrieve all leaflet markers on the map
getBounds Retrieve the current bounds for the map, if possible.
getCentre Get the lat/lng coordinates of the centre of the map view
getGeoJSON Retrieves the standard GeoJSON representation of all features that have been drawn on the map. Note that Circle objects are not supported by GeoJSON. Therefore, they are represented as Points in the resulting geometry. A workaround has been added to include 'point_type' = 'circle' and 'radius' properties in the feature's property object (this is still valid GeoJSON).
getMapId Retrieve the unique id for this map
getMapImpl Retrieve the underlying map implementation
getMarkerLocations Retrieve an array of objects of format [lat: x, lng: y] containing the coordinates of all markers on the map
markMyLocation Adds a marker at the user's current location. Will notify all subscribers.
notifyAll Notify all subscribers of an update to the map
redraw Invalidates the size of the map to trigger a re-draw, then fits the viewport to the current bounds.
registerListener Adds a listener for the specified event
removeLayer Removes the specified layer from the map.
removeListener Removes a listener for the specified event. Leaflet identifies listeners by references, so the original callback needs to be provided in order to find the listener to remove.
resetMap Removes all custom layers, reverts to the initial base layer, resets the zoom level to the default and re-centres the map. If fitToBoundsOf has been called previously, then resetMap will fit the map to the previously supplied bounds. To reset to the default map centre & zoom, call clearBoundLimits before resetMap. Will notify all subscribers.
setGeoJSON Populate the map with the provided GeoJSON data. If a Point feature's properties object contains "point_type: 'Circle' and "radius: {m}", then the point will be rendered as a circle. If the properties object of a feature includes a 'pid', then a new WMS layer will be added to the map instead of a polygon layer. See LAYER_OPTIONS for details of supported options. Will notify all subscribers.
setMaxBounds Zoom and centre the map to fit the provided bounds, and prevent the user from moving outside that boundary. Subsequent calls to Reset Map will automatically fit the map to the bounds of this object. The difference between this and fitToBoundsOf is that fitToBoundsOf will allow the user to pan outside the provided bounds, whereas this method will not.
startLoading Display a loading spinner on the map. Note: This is done automatically for any direct changes on the map.
subscribe Subscribe to all update events on the map. To listen for specific events, use ALA.Map#registerListener instead.
toggleFitBounds Toggle the view between fitting the bounds of the data and the initial centre and zoom
unsubscribe Stop listening to map update events.
zoom Zoom to the specified level and centre the map at the specified coordinates

addButton(style, closure, position)static

Adds a button to the map..

E.g. addButton('fa fa-map-marker', function (button, map) { ... }

Parameters

Name Type Description
style String The CSS style, or a HTML string with a span or image etc, for the button
closure function A function pointer for the function to be invoked. The first parameter of the function will be the leaflet button. The second parameter will be the leaflet map. I.e.
position String Leaflet Position value. Defaults to 'topleft'

addClusteredPoints(points, pointOptions)static

Adds a layer of clustered L.circleMarker to the map. Clustered points are treated the same as other layers/shapes: i.e. they are NOT considered to be 'markers' like those added with the #addMarker function.

See http://leafletjs.com/reference.html#path-options for the possible options.

Each point object in the points array must have the following structure:

  • lat - the latitude for the point. Mandatory.
  • lng - the longitude for the point. Mandatory.
  • popup - Text or HTML to be used as the popup when the marker is clicked. Optional.
  • options - options object to override specified options for the individual point. Optional.

Will notify all subscribers.

Parameters

Name Type Description
points Array Mandatory array of objects with mandatory properties 'lat' and 'lng', and optionally an 'options' object.
pointOptions Object Optional object containing configuration options to be applied to ALL points.

addControl(control)static

Adds a control widget to the map

Parameters

Name Type Description
control L.Control The Leaflet Control to add

addLayer(layer, layerOptions)static

Add a new layer to the map.

Will notify all subscribers.

Parameters

Name Type Description
layer Object The Leaflet ILayer to add
layerOptions Object Configuration options for the layer. See LAYER_OPTIONS for details of supported options. Optional.

addLayersControl(baseLayers, overlays, controlOptions)static

Add a layer selection control to the map. If options#defaultLayersControl = false, then this function can be used to place the layers control in a position other than the default (top right).

See http://leafletjs.com/reference.html#control-layers for details.

Parameters

Name Type Description
baseLayers Object Collection of base layers to add to the control
overlays Object Collection of overlay layers to add to the control
controlOptions Object config options

addMarker(lat, lng, popup, markerOptions) → {L.Marker}static

Adds a marker at the specified point.

Will notify all subscribers.

Parameters

Name Type Description
lat Number Latitude for the marker. Mandatory.
lng Number Longitude for the marker. Mandatory.
popup String Text or HTML to display in a popup when the marker is clicked. Optional.
markerOptions Object Object containing configuration items to override the defaults. Optional,

Returns

L.Marker The L.marker object

addPointsOrIcons(points, pointOptions, iconUrl, iconOptions)static

Adds a layer of points or icons to map. Icons gives the flexibility of adding shape to map.

Each point object in the points array must have the following structure:

  • lat - the latitude for the point. Mandatory.
  • lng - the longitude for the point. Mandatory.
  • type - supported values 'point' or 'icon'. point draws a circle and icon renders the provided image. Default 'point'.
  • popup - Text or HTML to be used as the popup when the marker is clicked. Optional.
  • options - options object to override specified options for the individual point. Optional.

Will notify all subscribers.

Parameters

Name Type Description
points Array Mandatory array of objects with mandatory properties 'lat' and 'lng', and optionally an 'options' object.
pointOptions Object Optional object containing configuration options to be applied to ALL points.
iconUrl String Optional image URL
iconOptions Object Optional object describing the icon metadata like size, anchor point, popup location.

addWmsLayer(pid, layerOptions) → {L.TileLayer.SmartWMS}static

Utility method to add a WMS layer to the map.

Triggers events draw:drawstart and draw:created, and will notify all subscribers

Parameters

Name Type Description
pid String the PID of the region to be displayed in the WMS layer - set as undefined if you do not need to use an existing region.
layerOptions Object Configuration options for the layer. If pid is undefined, then the layerOptions object must contain the required WMS configuration parameters. See LAYER_OPTIONS for details of additional supported options. Optional.

Returns

L.TileLayer.SmartWMS the L.TileLayer.WMS object

clearBoundLimits()static

Clears any limits on the map bounds. This will remove the max bounds (from setMaxBounds) and the display bounds (from fitToBoundsOf) if they exist. The map will be reset to the bounds of the current content (as per fitBounds).

clearLayers()static

Remove all drawn layers from the map. This does not remove markers: see self#clearMarkers.

Will notify all subscribers.

clearMarkers()static

Remove all markers from the map. This does not remove other layers or shapes: see self#clearLayers.

Will notify all subscribers.

countFeatures() → {Integer}static

Retrieve a count of all features (shapes, layers, markers, etc) on the map

Returns

Integer count of all features (shapes, layers, markers, etc) on the map

DEFAULT_OPTIONSstatic

Default Map options

DEFAULT_POINT_MARKER_OPTIONSstatic

Default options for clustered point markers.

See http://leafletjs.com/reference.html#path-options for the options: this object overrides the standard Leaflet options with our default values, where they are different.

destroy()static

Destroy the map and clear all related event listeners

finishLoading()static

Stop the loading spinner on the map.

Note: This is done automatically for any direct changes on the map.

fitBounds()static

Zoom and centre the map to fit the bounds of the current feature(s). If there are no features, then the map will be set to the default zoom and centre.

fitToBoundsOf(geoJSON)static

Zoom and centre the map to fit the bounds of the provided GeoJSON object, but do NOT draw the object.

Subsequent calls to Reset Map will automatically fit the map to the bounds of this object.

The difference between this and setMaxBounds is that setMaxBounds will prevent the user from panning outside the provided bounds, whereas this method will allow that.

Parameters

Name Type Description
geoJSON Object Valid GeoJSON object to fit the map to

getAllMarkers() → {Array}static

Retrieve all leaflet markers on the map

Returns

Array of all L.Markers on the map

getBounds() → {Object}static

Retrieve the current bounds for the map, if possible.

Returns

Object Leaflet Bounds object, or null if the bounds cannot be determined

getCentre() → {Object}static

Get the lat/lng coordinates of the centre of the map view

Returns

Object lat/lng object

getGeoJSON() → {GeoJSON}static

Retrieves the standard GeoJSON representation of all features that have been drawn on the map.

Note that Circle objects are not supported by GeoJSON. Therefore, they are represented as Points in the resulting geometry. A workaround has been added to include 'point_type' = 'circle' and 'radius' properties in the feature's property object (this is still valid GeoJSON).

Returns

GeoJSON Standard GeoJSON representation of the map's drawn features

getMapId() → {String}static

Retrieve the unique id for this map

Returns

String unique id of the map

getMapImpl() → {Object}static

Retrieve the underlying map implementation

Returns

Object Leaflet Map object

getMarkerLocations() → {Array}static

Retrieve an array of objects of format [lat: x, lng: y] containing the coordinates of all markers on the map

Returns

Array [lat: x, lng: y] of all markers

LAYER_OPTIONSstatic

Supported Layer options.

The following configuration options are available:

  • markerWithMouseOver - show a marker at the center of the layer, and hide the layer outline until the mouse is moved over the marker. Default: false
  • markerLocation - used with 'markerWithMouseOver' to specify the position of the marker - if not provided, the center of the layer's bounds will be used. Only works with a single feature.
  • popup - text or HTML to display when the layer (or the placeholder marker if markerWithMouseOver = true) is clicked.

markMyLocation()static

Adds a marker at the user's current location.

Will notify all subscribers.

notifyAll()static

Notify all subscribers of an update to the map

redraw()static

Invalidates the size of the map to trigger a re-draw, then fits the viewport to the current bounds.

registerListener(eventName, callback)static

Adds a listener for the specified event

Parameters

Name Type Description
eventName String the Leaflet event to listen to. Mandatory.
callback function The function to invoke when the event occurs. Mandatory.

removeLayer(layer)static

Removes the specified layer from the map.

Parameters

Name Type Description
layer Object the Leaflet Layer object to remove

removeListener(eventName, callback)static

Removes a listener for the specified event. Leaflet identifies listeners by references, so the original callback needs to be provided in order to find the listener to remove.

Parameters

Name Type Description
eventName String the Leaflet event being listened to. Mandatory.
callback function The function to invoke when the event occurs. Mandatory.

resetMap()static

Removes all custom layers, reverts to the initial base layer, resets the zoom level to the default and re-centres the map.

If fitToBoundsOf has been called previously, then resetMap will fit the map to the previously supplied bounds. To reset to the default map centre & zoom, call clearBoundLimits before resetMap.

Will notify all subscribers.

setGeoJSON(geoJSON, layerOptions)static

Populate the map with the provided GeoJSON data.

If a Point feature's properties object contains "point_type: 'Circle' and "radius: {m}", then the point will be rendered as a circle.

If the properties object of a feature includes a 'pid', then a new WMS layer will be added to the map instead of a polygon layer.

See LAYER_OPTIONS for details of supported options.

Will notify all subscribers.

Parameters

Name Type Description
geoJSON GeoJSON Standard GeoJSON metadata for map features. This can be a JSON string, or a GeoJSON object.
layerOptions Object Configuration options for the layer. See LAYER_OPTIONS for details of supported options. Optional.

setMaxBounds(latLngBounds)static

Zoom and centre the map to fit the provided bounds, and prevent the user from moving outside that boundary.

Subsequent calls to Reset Map will automatically fit the map to the bounds of this object.

The difference between this and fitToBoundsOf is that fitToBoundsOf will allow the user to pan outside the provided bounds, whereas this method will not.

Parameters

Name Type Description
latLngBounds LatLngBounds The Leaflet LatLngBounds object to restrict the map to

startLoading()static

Display a loading spinner on the map.

Note: This is done automatically for any direct changes on the map.

subscribe(callback) → {Object}static

Subscribe to all update events on the map.

To listen for specific events, use ALA.Map#registerListener instead.

Parameters

Name Type Description
callback function the callback function to be invoked when the map is updated

Returns

Object An object with a 'cancel' method that you can use remove this subscription.

toggleFitBounds()static

Toggle the view between fitting the bounds of the data and the initial centre and zoom

unsubscribe(callback)static

Stop listening to map update events.

Parameters

Name Type Description
callback function the callback function used to subscribe to events

zoom(zoom, centre)static

Zoom to the specified level and centre the map at the specified coordinates

Parameters

Name Type Description
zoom Number The zoom level
centre Object The coordinates to centre the map on. Must be an object with 'lat' and 'lng' attributes. Defaults to the map's default centre if not provided.