JS API
Map Object
QueryEngine Object
Layer Object
Feature Object
Query Object
GeoJson Function Library (Experimental)

Map Object

The Map object is the primary entry point for interacting with a Mapzania map. Its functionality includes things such as showing and hiding layers, panning and zooming and the filtering of layers.

The object can be instantiated in the following ways:

  1. new Mapzania.Map(elementId, mapKey) - no options or callback
  2. new Mapzania.Map(elementId, mapKey, callback) - callback only
  3. new Mapzania.Map(elementId, mapKey, options) - options only
  4. new Mapzania.Map(elementId, mapKey, options, callback) - options and callback

See the example below for more details.

Parameters

Name Required Description
elementId Yes The html id for the element (typically a div element) that will host the Mapzania map instance.
mapKey Yes The key of the map to be displayed.
param1 No If param2 is not set and this parameter is a function then it is a parameterless callback function, that is called when the map has finished initialising otherwise it is an object (which can be null) whose properties are used to configure the map. The possible option settings are shown in the table below.
param2 No A parameterless callback function, that is called when the map has finished initialising. This parameter is only used if param1 is set to an options object (which can be null).

Options

Name Default Description
debug false If this option is set to true, debug information is written to the console.
server null If the value is null, the Mapzania server that is used by the JavaScript API is the same the one from which the javascript is served.

If not, it should be a url to the api root of the server that will be used e.g. www.mapzania.com/mz (see example below).

NOTE: You will have to enable CORS in the server application to which you are connecting. See this article from Microsoft on how to enable CORS.
toolbar (default toolbar options) A object used to configure the toolbar.

See below for the valid settings of this object.

Toolbar Options

Name Default Description
layout Mapzania.Toolbar.Layouts.Simple

or, equivalently

["ZoomIn", "ZoomOut", "Reset"]
An array of button key strings, which the toolbar uses to determine which built-in buttons to display.

The lists of pre-defined layouts and built-in buttons are shown below.

Built-In Buttons

Key Description
'ZoomIn' Zooms the map in by 1 zoom step
'ZoomOut' Zooms the map out by 1 zoom step
'Reset' Resets the map to its starting bounds
'Pan' Sets the map to normal navigation (pan) mode
'DrawPoint' Sets the map to point-drawing mode
'DrawLine' Sets the map to line-drawing mode
'DrawPolygon' Sets the map to polygon-drawing mode

Pre-Defined Toolbar Layouts

Reference Value
Mapzania.Toolbar.Layouts.Simple ["ZoomIn", "ZoomOut", "Reset"]
Mapzania.Toolbar.Layouts.Standard ["ZoomIn", "ZoomOut", "Reset", "Pan", "DrawPoint", "DrawLine", "DrawPolygon"]

Example

// no callback or options      
var map = new Mapzania.Map("map-div", "LONDON"); 

// options only     
var map = new Mapzania.Map("map-div", "LONDON", { 
    debug: true, 
    toolbar: {
        layout: Mapzania.Toolbar.Layouts.Standard
    } 
});

// callback only     
var map = new Mapzania.Map("map-div", "LONDON", function() {
  console.log("Map started");
});

// options and callback     
var map = new Mapzania.Map("map-div", "LONDON", { 
    debug: true, 
    toolbar: {
        layout: ["ZoomIn", "ZoomOut"]
    } 
}, function() {
  console.log("Map started");
});

// external server     
var map = new Mapzania.Map("map-div", "LONDON", { 
    server: "www.mapzania.com/mz"
});

Methods

fitToBoundingBox

Sets the map view to contain a bounding box.

Parameters

Name Required Description
bbox Yes The bounding box that you want to contain in the view. If the bounding box has a different aspect ratio to the map, the map will make sure everything in the bounding box is visible.

The format of the bbox parameter is an array of numbers and conforms to the GeoJSON standard for a bounding box i.e. [minX, minY, maxX, maxY] where:

- minX (The minimum x-value of the bounding box)
- minY (The minimum y-value of the bounding box)
- maxX (The maximum x-value of the bounding box)
- maxY (The maximum y-value of the bounding box)
buffer No Expands (or contracts) the BoundingBox by this ratio. For example a value of 2 will make the bounding box twice as big and a value of 0.5 will make it half the size.

Example

var map = new Mapzania.Map("map-div", "WORLD");
map.fitToBoundingBox([12.1,3.4,14.3,4.2], 1.25);

getBoundingBox

Get the current bounding box of the map as is visible on the screen. The format of the result is an array of numbers and conforms to the GeoJSON standard for a bounding box i.e. [minX, minY, maxX, maxY].

Parameters

No parameters.

Example

var map = new Mapzania.Map("map-div", "WORLD");
console.log(map.getBoundingBox());
          
//OUTPUT
[3.6, -10.5, 4.7, -8.6]

getInitialBoundingBox

Get the initial bounding box of the map. The format of the result is an array of numbers and conforms to the GeoJSON standard for a bounding box i.e. [minX, minY, maxX, maxY].

Parameters

No parameters.

Example

var map = new Mapzania.Map("map-div", "WORLD");
console.log(map.getInitialBoundingBox());

//OUTPUT
[3.6, -10.5, 4.7, -8.6]

getLayers

Returns a list of information about the layers associated with the map.

Parameters

No parameters.

Example

var map = new Mapzania.Map("map-div", "WORLD", function(){
  var layers = map.getLayers();
  console.log(layers);
});
//OUTPUT
[
  {
    key:"STREETS",
    name:"Street Layer",
    ordinal:0,
    visible:true
  },
  {
    key:"SUBURBS",
    name:"Suburb Layer",
    ordinal:1,
    visible:false
  }
]

getMouseMode

Returns the current MouseMode of the map.

The MapMode determines the behaviour of the map based on mouse activity. Examples of this behaviour include zooming, panning and drawing on the map.

The available values are held by the Mapzania.MouseModes object and are:

  1. Pan (default)
  2. DrawPoint
  3. DrawLine
  4. DrawPolygon

Parameters

No parameters.

Example

var map = new Mapzania.Map("map-div", "WORLD");
console.log(map.getMouseMode());

//OUTPUT
1

off

Removes all event listeners for an event on the Map object.

Parameters

Name Required Description
type Yes The type (name) of the event for which to clear all listeners.

Example

var map = new Mapzania.Map("map-div", "WORLD");

map.on("roads_layer_queried", function (data) {
  console.log(data);
  map.off("roads_layer_queried");
});

on

Adds an event listener to the Map object. The listener will fire every time the event occurs.

Parameters

Name Required Description
type Yes The type (name) of the event for which to listen.
fn Yes The function to run when the event is fired. This function will be passed an object containing the event results. The properties of this object will depend on the event that was fired.

Example

var map = new Mapzania.Map("map-div", "WORLD", function(){
    map.on("streets_layer_changed", function (data) {
        console.log(data);
    });

    map.usingLayer("STREETS)
        .filterByText("StreetType=='HIGHWAY'")
        .update();
});

once

Adds an event listener to the Map object. The listener will fire once and then be disabled.

Parameters

Name Required Description
type Yes The type (name) of the event for which to listen.
fn Yes The function to run when the event is fired. This function will be passed an object containing the event results. The properties of this object will depend on the event that was fired.

Example

var map = new Mapzania.Map("map-div", "WORLD");

map.once("roads_layer_queried", function (data) {
    console.log(data);
});

var filter = Mapzania.Filters.filterByText("StreetType=='HIGHWAY'");

map.query("STREETS", filter, {
    ignoreAppliedFilters: true
}); 

refresh

Updates the map, by reloading all the visible layers using the current map bounds. This could be done, for example, if you changed some underlying data in your database.

Parameters

No parameters.

Example

var map = new Mapzania.Map("map-div", "WORLD");
// Code that changes underlying data
map.refresh();

reset

Zooms the map back to the starting bounds and sets the MapMode to Pan.

Parameters

No parameters.

Example

var map = new Mapzania.Map("map-div", "WORLD");
// Change the map mode and change the bounds of the map
map.reset();

setMouseMode

Sets the map mode which determines the behaviour of the map based on mouse activity. Examples of this behaviour include zooming, panning and drawing on the map.

When this method is called it fires the mouse_mode_set event.

Parameters

Name Required Description
mode Yes The mouse mode that you want the map to be in.

Valid options are:
-Mapzania.MouseModes.Pan (default)
-Mapzania.MouseModes.DrawPoint
-Mapzania.MouseModes.DrawLine
-Mapzania.MouseModes.DrawPolygon

NOTE: The last three modes fire the drawing_done event when completed. See manual for more details.

Example

var map = new Mapzania.Map("map-div", "WORLD");
map.setMouseMode(Mapzania.MouseModes.DrawPoint); 

usingLayer

Get a Layer Object from the map based on the key parameter.

This layer object is a fluent object and can be used to chain method calls to the layer as per the example below.

Parameters

Name Required Description
key Yes The key for the layer that will be used.

Example

var map = new Mapzania.Map("map-div", "AFRICA", function () {

    map.usingLayer("REGIONS")
        .hide();

    map.usingLayer("COUNTRIES")
        .filterByText("LandLocked=='Y'")
        .convertToCentroids()
        .style({ fillColor: "#0000FF"})
        .update();
});

usingNewLayer

Creates Layer Object with a key defined by the key parameter.

This layer object is a fluent object and can be used to chain method calls to the layer as per the example below.

NOTE: The layer created with usingNewLayer is a client-only layer. This means that it requires data to be added to it on the client. This is illustrated in the Feature Collection Filter Example.

Parameters

Name Required Description
key Yes The key for the new layer that will be created.

Example

var map = new Mapzania.Map("map-div", "AFRICA", function () {

  var geojson = {
    type: "FeatureCollection",
    features: [
      //... some feature data ...
    ]    
  };

    map.usingNewLayer("MY_LAYER")
      .addFeatureCollection(geojson)
      .filterByText("LandLocked=='Y'")
      .convertToCentroids()
      .style({ fillColor: "#0000FF"})
      .update();
});

Events

[layer_key]_layer_changed

Fired when the data in a layer changes. This can be due to map interaction such as zoom, pan or refresh.

[layer_key] is always the lowercase value of the layer key. For examples if the 'STREETS' layer changes, the event that is raised is 'streets_layer_changed'.


Event Result

A GeoJSON FeatureCollection.


Example

var map = new Mapzania.Map("map-div", "WORLD", function(){
    map.on("streets_layer_changed", function (data) {
        console.log(data);
    });

    map.usingLayer("STREETS)
        .filterByText("StreetType=='HIGHWAY'")
        .update();
});

mouse_mode_set

Fired when the user changes the MouseMode of the Map object.


Event Result

An integer value based on the MouseMode that was set.

MouseMode Value
Pan 1
DrawPoint 3
DrawLine 4
DrawPolygon 5

Example

var map = new Mapzania.Map("map-div", "LONDON", function () {

    map.on("mouse_mode_set", function (data) {
        console.log(data);
    });

    map.setMouseMode(Mapzania.MouseModes.Pan);
});

drawing_done

Fired when the user completes a drawing action on the map.


Event Result

GeoJSON Geometry based on the current MouseMode as per the table below:

MouseMode Result Type
DrawPoint GeoJSON Point
DrawLine GeoJSON LineString
DrawPolygon GeoJSON Polygon

Example

var map = new Mapzania.Map("map-div", "LONDON", function () {

    map.on("drawing_done", function (data) {
        console.log(data);
    });

    map.setMouseMode(Mapzania.MouseModes.DrawLine);
});

view_changed

Fired when the view is changed by the user due to panning or zooming.


Event Result

An json object with the following properties:

MouseMode Result Type
boundingBox GeoJSON bounding box
zoom integer
center GeoJSON Point

Example

var map = new Mapzania.Map("map-div", "LONDON", function () {

    map.on("view_changed", function (data) {
        console.log(data);
    });

    map.fitToBoundingBox([10,10,20,20]);
});