Documentation

Class

Map

ALA.Map(id, options)

Constructor

# new Map(id, options)

Object for interacting with a generic map.

Options

  • autoZIndex If true, the control will assign zIndexes in increasing order to all of its layers so that the order is preserved when switching them on/off. Default: true
  • preserveZIndex If true, a added layer will not be brought to front. It will be at the zIndex assigned. Default: false
  • baseLayer The base layer shown by default. Can be one of: - a Leaflet.Layer object, or - a string containing the name of one of the built-in base layers. Available built-in base layers: 'Minimal', 'WorldImagery', 'Detailed', 'Topographic'. Default: 'Minimal'.
  • otherLayers Specifies the base layers that will be available (including the default baseLayer). This is an object, where the keys are the display text, and values are either: - a Leaflet.Layer object, or - the name of one of the built-in base layers. Default: {'Minimal': 'Minimal', 'World Imagery': 'WorldImagery'}.
  • overlays Specify the overlays that should be added to map. The expected format is { 'Australian Corals': L.tileLayer.wms }
  • overlayLayersSelectedByDefault List of overlays to be shown on map by default. This works in conjunction with 'overlays' option. Overlays not on this list will have a checkbox to show on map. The expected format is ['Australian Corals']
  • center Centre position of the map. Default: -28, 134
  • zoom the initial zoom level. Default: 4
  • maxZoom the maximum allowed zoom level. Default: 21
  • 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
  • addLayersControlHeading true to add heading to base layer and overlay sections of the selector, false to use your own. Default: false
  • 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
  • addGeometryFromLocalFile add a shape from a file. Accepted formats are shapefile, geojson, kml, gpx. Default: false
  • simplifyImportedShapes True to simplify shapes imported from files. Only relevant if addGeometryFromLocalFile = true. Default: false
  • simplifyOptions Options to pass to the turf's simplify method. Only relevant if addGeometryFromLocalFile = true and simplifyImportedShapes = true. Default: {tolerance: 0.001, highQuality: true, mutate: 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'.
  • trackWindowHeight Map will adjust its height according to the height of browser window when set to true. Default: false.
  • minMapHeight The height of map will not go below this value. It is only active when trackWindowHeight is true. Default: 250.
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.

View Source Map.js, line 111

Members

# static DEFAULT_OPTIONS

Default Map options

View Source Map.js, line 253

# static 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.

View Source Map.js, line 328

# static 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.

View Source Map.js, line 313

Methods

# static addButton(style, closure, position)

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'

View Source Map.js, line 1074

# static addClusteredPoints(points, pointOptions)

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.

View Source Map.js, line 646

# static addControl(control)

Adds a control widget to the map
Parameters:
Name Type Description
control L.Control The Leaflet Control to add

View Source Map.js, line 1063

# static addLayer(layer, layerOptions)

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.

View Source Map.js, line 792

# static addLayersControl(baseLayers, overlays, controlOptions) → {L.Control.Layers}

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). If the layer control has already been added, then the baselayers and overlays will be added to the existing control. The controlOptions will be ignored. See http://leafletjs.com/reference.html#control-layers for details.
Parameters:
Name Type Description
baseLayers Object Collection of base layers with names to add to the control
overlays Object Collection of overlay layers with names to add to the control
controlOptions Object config options, including overlayLayersSelectedByDefault: List of String

View Source Map.js, line 1184

added layer control
L.Control.Layers

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

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,

View Source Map.js, line 616

The L.marker object
L.Marker

# static addOverlayLayer(layer, name, isSelected)

Add a layer to the map as an overlay layer.
Parameters:
Name Type Description
layer L.Class The tile layer or other type of layer to add as an overlay layer.
name string The name text to show for this layer.
isSelected boolean Whether the added overlay layer should start selected, and therefore visible, or not.

View Source Map.js, line 846

# static addPointsOrIcons(points, pointOptions, iconUrl, iconOptions)

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.

View Source Map.js, line 704

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

Utility method to add a WMS layer to the map. Triggers events pm:drawstart and pm:create, 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.

View Source Map.js, line 815

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

# static 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).

View Source Map.js, line 1035

# static clearLayers()

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

View Source Map.js, line 556

# static clearMarkers()

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

View Source Map.js, line 590

# static countFeatures() → {Integer}

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

View Source Map.js, line 1124

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

# static destroy()

Destroy the map and clear all related event listeners

View Source Map.js, line 358

# static finishLoading()

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

View Source Map.js, line 1152

# static 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.

View Source Map.js, line 938

# static fitToBoundsOf(geoJSON)

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

View Source Map.js, line 968

# static getAllMarkers() → {Array}

Retrieve all leaflet markers on the map

View Source Map.js, line 1096

of all L.Markers on the map
Array

# static getBounds() → {Object}

Retrieve the current bounds for the map, if possible.

View Source Map.js, line 900

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

# static getCentre() → {Object}

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

View Source Map.js, line 604

lat/lng object
Object

# static getGeoJSON() → {GeoJSON}

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

View Source Map.js, line 450

Standard GeoJSON representation of the map's drawn features
GeoJSON

# static getMapId() → {String}

Retrieve the unique id for this map

View Source Map.js, line 508

unique id of the map
String

# static getMapImpl() → {Object}

Retrieve the underlying map implementation

View Source Map.js, line 519

Leaflet Map object
Object

# static getMarkerLocations() → {Array}

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

View Source Map.js, line 1107

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

# static getOverlayLayers(filter) → {array}

Get the overlay layers.
Parameters:
Name Type Description
filter string Which layers to include: 'all': all layers; 'selected': only selected layers. Default 'all'.

View Source Map.js, line 867

selected or all overlay layers, depending on the filter parameter.
array

# static getTopSelectedOverlayLayer() → {null|L.Class}

Get the most recently selected overlay layer.

View Source Map.js, line 886

The most recently selected layer or null if no layers are selected.
null | L.Class

# static markMyLocation()

Adds a marker at the user's current location. Will notify all subscribers. Fire a 'SearchEventFired' for site creation

View Source Map.js, line 764

# static notifyAll()

Notify all subscribers of an update to the map

View Source Map.js, line 409

# static redraw()

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

View Source Map.js, line 1051

# static registerListener(eventName, callback)

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.

View Source Map.js, line 421

# static removeLayer(layer)

Removes the specified layer from the map.
Parameters:
Name Type Description
layer Object the Leaflet Layer object to remove

View Source Map.js, line 576

# static removeListener(eventName, callback)

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.

View Source Map.js, line 437

# static 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.

View Source Map.js, line 530

# static setGeoJSON(geoJSON, layerOptions)

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.

View Source Map.js, line 465

# static setMaxBounds(latLngBounds)

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

View Source Map.js, line 1019

# static startLoading()

Display a loading spinner on the map. Note: This is done automatically for any direct changes on the map.

View Source Map.js, line 1140

# static subscribe(callback) → {Object}

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

View Source Map.js, line 376

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

# static toggleFitBounds()

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

View Source Map.js, line 1164

# static unsubscribe(callback)

Stop listening to map update events.
Parameters:
Name Type Description
callback function the callback function used to subscribe to events

View Source Map.js, line 395

# static zoom(zoom, centre)

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.

View Source Map.js, line 925

# inner addCustomCancelActionToEditModes()

Adding custom cancel button as Geoman free version does not come with cancel button.

View Source Map.js, line 1767

# inner addFileInputControl(options) → {*}

Adds a file input control to the map using the leaflet-filelayer plugin, which allows the user to load GeoJSON, KML, GPX or Shapefile (in zip format) files from their local machine onto the map. The file is parsed and added as a layer to the map, with support for WMS layers if the GeoJSON features have a 'pid' property.
Parameters:
Name Type Description
options

View Source Map.js, line 2108

*

# inner addKnownShapeControl(options)

Creates an instance of the L.Control.TwoStepSelector control and adds it to the map. This control allows the user to select a layer from a list of layers, and then select a shape from that layer, which is then added to the map as a WMS layer.
Parameters:
Name Type Description
options

View Source Map.js, line 2151

# inner assignFeatureId(layer, feature)

Assign a unique featureId property to the feature and layer if it does not already exist.
Parameters:
Name Type Description
layer
feature

View Source Map.js, line 1999

# inner cancelGlobalModeChanges(modeName)

Restore map to state before mode was enabled, and disable the mode. This is triggered when the user clicks the custom cancel button added to the mode actions.
Parameters:
Name Type Description
modeName

View Source Map.js, line 1824

# inner disableGlobalMode(modeName)

Disable the global mode if it is enabled. This is used when cancelling an edit action to turn off the mode that was turned on when the snapshot was taken.
Parameters:
Name Type Description
modeName

View Source Map.js, line 1849

# inner handleGlobalModeToggle(modeName, enabled)

Take a snapshot of the current map state when an edit mode is enabled to restore state if the action is cancelled in the future.
Parameters:
Name Type Description
modeName
enabled

View Source Map.js, line 1800

# inner initDrawingControls(currentOptions)

Initialise the drawing controls that appear on the left side of the map panel
Parameters:
Name Type Description
currentOptions

View Source Map.js, line 1599

# inner onEachFeatureWithWMSLayerSupport(feature, layer, layerOptions)

Callback function for rendering GeoJSON features. This function supports rendering WMS layers for features with a 'pid' property, and also supports creating popups based on feature properties.
Parameters:
Name Type Description
feature
layer
layerOptions

View Source Map.js, line 1934

# inner overlayLayerAdd(layer, name, isSelected)

Internal function to add an overlay layer to the layers control.
Parameters:
Name Type Description
layer L.Class Layer to add.
name String Text to display for the layer.
isSelected Boolean Whether to add the layer in the selected state or not.

View Source Map.js, line 2334

# inner overlayLayerDeselect(layer)

Internal function to de-select an overlay layer.
Parameters:
Name Type Description
layer L.Class

View Source Map.js, line 2381

# inner overlayLayerRemove(layer)

Internal function to remove an overlay layer from the layers control.
Parameters:
Name Type Description
layer L.Class The layer to remove.

View Source Map.js, line 2353

# inner overlayLayerSelect(layer)

Internal function to select an overlay layer.
Parameters:
Name Type Description
layer L.Class

View Source Map.js, line 2370

# inner populateDefaultBaseLayerOptions(currentOptions)

Sets up map base layers - options.baseLayer specifies the default and options.otherLayers specifies the available base layers. If baseLayer is not set, it will be set to the default base layer. If otherLayers is not set, it will be set to the default list, with the default base layer included if it is one of the pre-defined base layers. If otherLayers is provided, the layer set as baseLayer must be included in the otherLayers object.
Parameters:
Name Type Description
currentOptions

View Source Map.js, line 1484

# inner populateDefaultOptions(currentOptions)

Populate any missing configuration items with the default values.
Parameters:
Name Type Description
currentOptions

View Source Map.js, line 1468

# inner updateFeatureProperties(feature, layer)

Assign the feature properties to the layer, ensuring that if the layer already has feature properties, they are not overwritten but merged with the new properties.
Parameters:
Name Type Description
feature
layer

View Source Map.js, line 1977