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

Options

Toolbar Options

Built-In Buttons

Pre-Defined Toolbar Layouts

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

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

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

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

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

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

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

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.

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:

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:

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]);
});