API Reference

Any classes not defined here mimic the Leaflet 1.0.0-rc1 reference.

Map

Usage example

An instance of Maze.Map works as its Leaflet counterpart:

    <div id='mazemap-container' style='width:600px; height:400px;'></div>
    <script>
        var map = Maze.map('mazemap-container');
        map.setView([63.41, 10.41], 12);
    </script>

By default, an instance of Maze.Map adds the functionality for switching campuses and updating the available floors in the z-level control by focusing on a different area of the map. These can be enabled or disabled as Leaflet handlers:

    var map = Maze.map('mazemap-container', { campusloader: false });
    map.campusloader.enable();
    map.zlevelupdater.disable();

Options

Option Type Default Description
zlevelupdater Boolean 'true' Whether to update the default z-level control automatically or not.

Campus loading options

Option Type Default Description
campuses String 'default' Which set of campuses to load at start-up
campusloader Boolean true Whether to load campuses at start-up and disable/enable them when the user moves around.

Z-Level options

Option Type Default Description
zLevel Number Initial map z-level

Events

Campus loading events

Event Data Description
campuschange Fired then the campus loader activates a new campus.

Z-Level events

Event Data Description
zlevel Fired when the map's z-level changes. The event has a zLevel property containing the newly set z-level.

Methods

Method Returns Description
getZLevelControl() Control.ZLevel Returns the Z-level control that this map instance uses.

Floorplan display methods

Methods used internally for displaying floorplans in an efficient manner which fits the MazeMap floorplan rendering backend.
Method Returns Description
showCampusFloor(<Number> campusId, <Number> floorId) this Adds the campus-floor combination to the list of floorplans to be queried.
hideCampusFloor(<Number> campusId, <Number> floorId) this Removes the campus-floor combination to the list of floorplans to be queried.

Z-Level methods

Method Returns Description
setZLevel(Number) this Sets the map's z-level
getZLevel() Number Gets the current map's z-level

Data

Provides a common way of fetching automatically cacheable data from the MazeMap backend. Requires the user's web browser to implement the Fetch interface. Consider using a polyfill for making this work in all browsers. This also means that all methods return asynchronous Promises instead of directly returning a value. The data returned is raw JSON from the MazeMap backend, might have no direct use, and might be subject to change. Usage of Instancer is recommended instead.

Usage example

Maze.Data.getCampuses().then( campuses => {
    console.log(campuses); // Raw data about the campuses.
});

Functions

Function Returns Description
getBuilding(<Number> buildingId) Promise→GeoJSON Returns a Promise for one Building data, given its ID.
getBuildingsByCampusId(<Number> campusId) Promise→[GeoJSON] Returns a Promise of an array of Building data, with all the buildings in the given campus. Note this is not a GeoJSON FeatureCollection.
getCampuses(<String> collection?) Promise→[GeoJSON] Returns a Promise to a flat array with a set of Campus data GeoJSON objects. Note this is not a GeoJSON FeatureCollection. If not specified, collection will assume a value of 'default'.
getCampusesTree(<String> collection?) Promise→{} Returns a Promise to a tree-like structure of all campuses and campus groups. If not specified, collection will assume a value of 'default'.
getCampus(<Number> campusId) Promise→GeoJSON Returns a Promise for one Campus data, given its campusId.
getPoi(<Number> campusId) Promise→GeoJSON Returns a Promise for POI data, given the POI ID.
getPoiCategoryIdsByCampusId(<Number> campusId) Promise→[Number] Returns a Promise for a plain array of POI category IDs, the ones readily available in that campus.
getPoiCategoryStyleById(<Number> poiCategoryId) Promise→{} Returns a Promise for a plain object, containing the Marker options to properly style a POI of the given category.
getPoisByCategoryAndCampusId(<Number> poiCategoryId, <Number> campusId) Promise→GeoJSON Returns a Promise for a GeoJSON FeatureCollection, each of its features being POI data, for all POIs of the given category in the given campus.
getPoiAt(<LatLng> latlng, <Number> zLevel?) Promise→GeoJSON Returns a Promise for POI data corresponding to the POI in the given z-level, closest to the given LatLng. The promise may resolve to false if there are no POIs around.
getFloor(<Number> floorId) Promise→GeoJSON Returns a Promise for one Floor data, given the floor ID.
getFloorsByCampusId(<Number> campusId) Promise→[GeoJSON] Returns a Promise for an array of Floor data. Note this is not a GeoJSON FeatureCollection.

Building data

Methods like Maze.Data.getBuilding() return a GeoJSON object with a polygon geometry and the following properties:
Property Type Description
id Number Numeric ID of the building (globally unique).
campusId Number Numeric ID of the campus this building belongs to.
name String Name of the building.
floors [{}] An array of plain objects with raw information about the floors this building has. Note this is neither a GeoJSON FeatureCollection nor an array of floors as GeoJSON.

Campus data

Methods like Maze.Data.getCampus() return a GeoJSON object with a polygon geometry and the following properties:
Property Type Description
id Number Numeric ID of the campus (globally unique).
name String Name of the campus.
routing Boolean true if the campus supports calculating routes.
wheelchair Boolean true if the campus supports calculating routes which avoid stairs and obstacles.
campusTypeId String Lowercase string indicating the campus type, e.g. university or hospital.

POI data

Methods like Maze.Data.getPoisByCategoryAndCampusId return POI data. POIs (short for 'points of interest') are named points or rooms, as defined when editing the building data or when importing information from a building management system. POIs fetched from Maze.Data are GeoJSON objects with a geometry (a polygon in case of rooms, or a point in case of POIs without a specific room), and the following properties:
Property Type Description
id Number Numeric ID of the POI, globally unique.
name String Name of the POI or room.
identifier String Textual identifier of the POI/room, unique within the campus (not globally unique).
campusId Number Numeric ID of the campus this POI belongs to.
floorId Number Numeric ID of the floor this POI belongs to.
zLevel Number Z-level this POI belongs to. Is undefined for outdoor POIs like bus stops.

Floor data

Methods like Maze.Data.getFloor() return a GeoJSON object with a polygon or multipolygon geometry and the following properties:
Property Type Description
id Number Numeric ID of the floor (globally unique).
buildingId Number Numeric ID of the building this floor belongs to (globally unique).
campusId String Numberic ID of the campus this floor belongs to.
name String Name of the floor, usually similar to the z-level.
flags []
z Number Z-level of this floor

Instancer

Provides async factory methods for campuses, buildings, floors, POIs. Instead of returning just an instance, the methods in this handler return Promises of instances. Instancer relies on Data, so it requires the user's web browser to implement the Fetch interface. Instances of Campus, Building and Floor can be added to a map. Instancer returns new instances, it doesn't cache or reuse them. That is the responsability of the code calling Instancer.

Usage example

Maze.Instancer.getCampus(1).then( campus => {
    map.addLayer(campus);
});

Functions

Function Returns Description
getCampus(<Number> campusId) Promise→Campus Returns a Promise to an instance of Campus, given the campus ID.
getCampuses(<String> collection?) Promise→[Campus] Returns a Promise to a flat array of instances of Campus, given the campus collection name. If no collection is provided, the default one is assumed.
getBuilding(<Number> buildingId) Promise→Building Returns a Promise to an instance of Building, given the building's ID.
getBuildingsByCampusId(<String> collection) Promise→[Building] Returns a Promise to a flat array of instances of Building contained in a Campus, given the campus ID.
getFloor(<Number> floorId) Promise→Floor Returns a Promise to an instance of Floor, given the floor's ID.
getFloorsByCampusId(<Number> floorId) Promise→Floor Returns a Promise to a flat array of instances of Floor contained in a Campus, given the campus ID.
getPoi(<Number> poiId, <Marker options> options?) Promise→Marker Returns a Promise to a Marker representing the given POI. Any marker options given will override the default marker options.
getPoisByCategoryAndCampusId(<Number> floorId) Promise→Floor Returns a Promise to a plain array of Markers.
getPoiAt(<LatLng> latlng, <Number> zLevel?) Promise→Marker Returns a Promise for a Marker, corresponding to the POI in the given z-level, closest to the given LatLng. The promise may resolve to false if there are no POIs around.

Campus

Represents a campus. Logically, a campus is an area with some attributes (id, name) and references to a set of Buildings.

Usage example

Instances of Maze.Campus should be fetched from the instancer static methods.

Maze.Instancer.getCampus( 1 ).then(function(campus){
    console.log(campus.getName());    // e.g. "Gløshaugen"
});

Events

Event Data Description
active Fired when a campus is set as active and will start loading its buildings.
load Fired when a campus has finished loading all the buildings it contains.
inactive Fired when a campus is set as inactive.

Methods

Method Returns Description
setActive() Promise→this Sets the campus as active. This loads and then shows buildings inside the campus. This operation is (potentially) asynchronous. The result value is a Promise that will resolve when the all data has been loaded.
setInactive() this Sets the campus as inactive. This hides buildings inside the campus.
getId() Number Returns the campus ID (persistent)
getName() String Returns the campus name
getBounds() LatLngBounds Returns the campus' rectangular LatLngBounds.
getCenter() LatLng Returns the centroid of the campus.
getAvailableZLevels() [Number] Returns a Set containing all z-level indexes this campus has a floor at.
getBuildings() [Building] Returns a plain array containing all the Buildings inside the campus. Returns an empty array if the campus is not set active.
getBuilding(<Number> buildingId) Building Returns the already existing instance of a building in the campus given its ID, or undefined if that building is not part of the campus, or if the campus is not set as active.
setOutlineStyle(<Path options> style) this Changes the appearance of the campus outline. style is a set of Leaflet Path options
getMarkerCluster() MarkerCluster Returns a reference to the MarkerCluster this campus uses for its POIs.
addMarker(<Marker> marker) this Adds the given marker to the campus' MarkerCluster
addMarkers(<[Marker]> markers) this Adds the given markers to the campus' MarkerCluster
removeMarker(<Marker> marker) this Removes the given marker from the campus' MarkerCluster
removeMarkers(<[Marker]> markers) this Removes the given markers from the campus' MarkerCluster
addPoiCategory(<Number> poiCategoryId) this Adds all POIs from the given category as markers. This operation is asynchronous: it returns a Promise for this that resolves when the POIs have been added.
removePoiCategory(<Number> poiCategoryId) this Removes all markers representing POIs from the given category

Building

Represents a physical building. Logically, a building is an area with some attributes (id, name) and references to a set of Floors.

Usage example

Instances of Maze.Building should be fetched from the instancer static methods.

Maze.Instancer.getBuildingById( 1 ).then( function(building){
    console.log(building.getName()); // e.g. "Sentralbygg"
    console.log(building.getAvailableZLevels()); // e.g. [-2, -1, 1, 1.5, 2, 3, 4]
} );

Events

Event Data Description
load Fired when a building has finished loading all the floors it contains.

Methods

Method Returns Description
getId() Number Returns the building ID (persistent and unique per campus)
getName() String Returns the building name
getBounds() LatLngBounds Returns the building's rectangular LatLngBounds.
getCenter() LatLng Returns the centroid of the building.
getCampusId() Number Returns the campus ID this building belongs to.
getAvailableZLevels() [Number] Returns a plain array containing all z-level indexes this building has a floor at.
getFloors() {Floor} Returns a plain object containing z-levels as keys and instances of Floor as values.
getFloor(<Number> zLevel) Floor Returns the Floor this building has at zLevel (or undefined if there is nothing at that z-level).
setOutlineStyle(<Path options> style) this Changes the appearance of the building outline. style is a set of Leaflet Path options

Floor

Represents a horizontal slice of a building. Logically, a floor is an area with some attributes (id, name, z-level).

Usage example

Instances of Maze.Floor should be fetched from the instancer static methods.

Maze.Instancer.getFloorById( 1 ).then( function(floor){
    console.log(floor.getName());
    console.log(floor.getZLevel());
} );

Methods

Method Returns Description
getId() Number Returns the floor ID (might change if floorplan is updated)
getName() String Returns the floor name
getBounds() LatLngBounds Returns the floor's rectangular LatLngBounds.
getCenter() LatLng Returns the centroid of the floor.
getCampusId() Number Returns the campus ID this floor belongs to.
getBuildingId() Number Returns the building ID this floor belongs to.
getZLevel() Number Returns the Z-Level of this floor
setOutlineStyle(<Path options> style) this Changes the appearance of the floor outline. style is a set of Leaflet Path options

Version

Properties

Property Type Description
Maze.version Indicates the version of the MazeMap JS API, e.g. "1.0.1".
Maze.leafletVersion Indicates the LeafletJS version bundled, e.g. "1.0.0".

Util

Functions

Function Returns Description
jsonFromResponse() {} Returns the JSON data corresponding to a fetch API request, or throws an error. Useful when chained to a fetch Promise.
equalArrays(Array) Boolean Returns true if the arrays have the same length and each element is the same in both.

Z-Level utility functions

Maze.Util has a few static methods to help manage lists of z-levels.
Function Returns Description
upperZInList(<Number> z, <[Number]> zs) Number|null Returns the upper (inmediately greater) Z in the list of available Zs, or null if there is no greater Z.
lowerZInList(<Number> z, <[Number]> zs) Number|null Returns the lower (inmediately smaller) Z in the list of available Zs, or null if there is no smaller Z.
nearestZInList(<Number> z, <[Number]> zs) Number|null Returns the nearest Z in the list of available Zs, or null if Zs is empty.

Properties

Property Type Description
undefinedPromise Promise A Promise which inmediately resolves to undefined.

Icon.Chub

A subclass of Leaflet.Icon.Glyph implementing the MazeMap defaults.

Creation

Factory Description
Maze.icon.chub(<Icon.Chub options> options) Returns a new icon with the given options.

Options

Option Type Default Description
prefix String 'mdi' The prefix for the glyph font to be used. Defaults to the Material Design Icons glyph font.
color String 'orange' The background of the icon. Can be either 'red', 'orange', 'yellow', 'lime', 'green', 'teal', 'cyan', 'blue', 'indigo', or 'magenta'.
cluster Number 1 How many datapoints this icon represents, useful for using an icon for a cluster of points.
glyph String 'checkbox-blank-circle' The name of the glyph
glyphColor String 'white' The CSS color of the glyph
glyphSize String '25px' The size of the glyph, in CSS units Glyph offset from the icon's center, in CSS pixels

Icon.Bubble

A subclass of Icon.Chub with a flatter appearance

Creation

Factory Description
Maze.icon.bubble(<Icon.Bubble options> options) Returns a new icon with the given options.

Marker

Usage example

// A bus stop, always visible
Maze.marker([63.41, 10.39], {
    icon: Maze.icon.chub({colour: 'green', glyph:'bus'})
}).addTo(map);
// A computer room in the 3rd floor
Maze.marker([63.42, 10.39], {
    icon: Maze.icon.chub({colour: 'indigo', glyph:'laptop'}),
    offZIcon: Maze.icon.chub({colour: 'blue', glyph:'laptop'}),
    offZOpacity: 0.3,
    zLevel: 3
}).addTo(map);

Options

Z-Level options

Option Type Default Description
zLevel Number|[Number] undefined The z-level this marker belongs to. If set, clicking on the marker will focus that z-level. If set to an array of Numbers, the marker will "belong" to all of them, and clicking on the marker will cycle through them.
icon Icon The Icon to be shown when the map's z-level equals the marker's.
offZIcon Icon undefined The Icon to be shown when the map's z-level does not equal the marker's. If not set, the marker will have the same icon when switching through z-levels.
offZOpacity Number undefined The marker opacity when the map's z-level does not equal the marker's. If not set, the marker will have the same opacity when switching through z-levels.

Handler.CampusLoader

This map handler tracks changes of the map's viewport, activating and deactivating campuses so only the campus in the center of the viewport is active. This also displays the default z-level control after a campus has been activated, and sets the z-level to 1 (or, if a campus has a default starting z-level, to that value).

Usage example

This map handler can be disabled by setting the map option campusloader to false. When the campus loader is disabled,

var map = Maze.map('mazemap-container',{
    campusloader: false
});
Maze.Instancer.getCampus(1).then(function(campus){
    campus.addTo(map).setActive();
    map.fitBounds(campus.getBounds());
    map.setZLevel(1);
});

By default, the default campuses are loaded. To load a different set of campuses at start-up:

var map = Maze.map('mazemap-container',{
    campusloader: true,
    campuses: 'ntnu'
});

Handler.ZLevelUpdater

This map handler tracks changes of the map's viewport, checking which buildings are currently visible, and (re)sets the available z-levels and the current floor name in the default z-level control. Note that the default z-level control might not be visible, particularly if campuses are not being loaded automatically.

Usage example

Extra checks of the available z-levels are possible:

var map = Maze.map('mazemap-container',{
    zlevelupdater: true
});
window.setInterval(function(){
    map.zlevelupdater.checkAvailableZLevels();
}, 10000);

Methods

Method Returns Description
checkAvailableZLevels(<Boolean> force?) {} Populates the values for the default z-level control based on the buildings visible on the viewport. Returns the mapping of z-levels and names used. If force is set to false, a cached version of the available z-levels will be used for performance. If buildings have changed, use true.

Route

Functions

Function Returns Description
getGeoJsonRoute(<LatLng> startLatLng, <Number> startZLevel, <LatLng> endLatLng, <Number> endZLevel, <Route options> options?) Promise→GeoJSON Performs a route query, and returns a Promise to a GeoJSON FeatureCollection
getFeatureGroupRoute(<LatLng> startLatLng, <Number> startZLevel, <LatLng> endLatLng, <Number> endZLevel, <Route options> options?) Promise→FeatureGroup Performs a route query, and returns a Promise to a FeatureGroup with Polylines and Markers

Route options

Option Type Default Description
avoidStairs Boolean false Whether to avoid stairs during the route calculation.
elevatorPoints Boolean true Whether to replace elevator route segments with a point/marker
stairPoints Boolean true Whether to replace stair route segments with a point/marker
connectToStart Boolean true Whether the start point is part of the path. If set to false, the path will start at the closest point in the routing graph.
connectToEnd Boolean true Whether the end point is part of the path. If set to false, the path will start at the closest point in the routing graph.

Search

Functions

Function Returns Description

Search result

Search results are plain objects, containing the GeoJSON of the result entity (See POI data, Building data, Campus data).
Property Type Description
title String The name of the search result, with HTML <em> tags marking the part of the name which matched the search term.
type String Either 'poi', 'building' or 'campus'.
geojson GeoJSON An instance of POI data, Building data or Campus data.

Search options

Option Type Default Description
resultsMax Number 10 Maximum number of search results.
resultsSkip Number 0 Skip this many search results, most useful when paginating search results.
campusId Number undefined If used, the search results will be retricted to the given campus, and the campuses option will be ignored.
campuses String 'default' If used, the search results will be retricted to the given campuses set.
searchForPois Boolean true Whether search results can include POIs.
searchForPoiCategories Boolean true Whether search results can include POI catrgoriess.
searchForBuildings Boolean true Whether search results can include buildings.
searchForCampuses Boolean true Whether search results can include campuses.

Handler.LIPILocation

This map handler provides location functionalities for MazeMap's LIPI indoor positioning, in a manner similar to Leaflet's default geopositioning.

Usage example

Geolocation queries in vanilla Leaflet look like this:

var map = L.map();
map.locate( { watch: true } );
map.on('locationfound', function(ev) {
    // 'ev' is a LocationEvent
    map.setView(ev.latlng);
});

LIPI location queries look like this:

var map = L.map();
map.lipiLocation.locate( { watch: true } );
map.lipiLocation.on('locationfound', function(ev) {
    // 'ev' is a LocationEvent, with an extra `zLevel` property
    map.setView(ev.latlng);
    // map.fitBounds(data.bounds);
    console.log(ev.zLevel);
});

Functions

Function Returns Description
locate(<Locate options> options) this Starts a LIPI location query, which will trigger either a locationfound or locationerror event. The location query will be repeated if the watch option is set to true. The map will be set to the user location if the setView option is set to true.
stopLocate() this Stops any further LIPI location queries, if a previous call to locate({ watch: true }); was made.

Properties

Property Type Description
siteResolver String Which URL to use as a "site resolver". MazeMap's site resolver looks at the IP address of a client and then points to the LIPI servers available for that IP range.

Control.ZLevel

A map control similar to the zoom control in appearance, that controls the active z-level of the map. Some map layers can have a different behaviour or appearance based on the z-level. For example, a tile layer for rooms in a given floor might be shown only at a z-level, or a marker at a z-level might be semi-transparent if the map's z-level is not the marker's z-level.

Creation

Factory Description
Maze.control.zLevel(options) Instantiates a new Control.ZLevel given a set of options.

Options

Option Type Default Description
zLevelUpText String '🏢↑' Text shown on the "Z-level up" button
zLevelUpTitle String 'Level up' Title of the "Z-level up" button (show on tooltip)
zLevelDownText String '🏢↓' Text shown on the "Z-level down" button
zLevelDownTitle String 'Level down' Title of the "Z-level down" button (show on tooltip)
zLevels {} undefined An optional initial set of Z-levels, as per updateZLevels. The value of option is updated on every call to updateZLevels with the latest passed values.

Methods

Method Returns Description
updateZLevels(<{}> zLevels) this Sets the valid z-levels for this control. Parameter must be a key/value map (or plain object) with z-levels as keys and short names as values, e.g. { -1: "U", 0: "G", 1: 1 }
getZLevel() Number Returns the map's active z-level
setZLevel() Number Sets the map's z-level
hide() this Hides the control
show() this Shows (unhides) the control

Path

Options

Z-Level options

Option Type Default Description
zLevel Number undefined The z-level this path belongs to.
offZStyle Path options A set of Path options (stroke, color, weight, opacity, lineCap, lineJoin, dashArray, dashOffset, fill, fillColor, fillOpacity, fillRule) to use when the map's z-level does not equal the map's. If not set, the vector overlay will have the same style when switching through z-levels. Path options not specified will be inherited from the normal path options.

LayerGroup.ZDemuxer

A subclass of Layergroup, it allows to add sets of layers pertaining to a z-level, and show/hide these sets whenever the map's z-level changes.

Creation

Factory Description
Maze.layerGroup.zDemuxer(<{}> layers) Given a hashmap (or plain object) containing z-levels as keys and layers (or arrays of layers) as values (e.g. {1: layer1, 2: [layer2, layer3]}), creates the layer group and initializates the layers in each z-level.

Methods

Method Returns Description
addLayer(<Layer> layer, <Number> zLevel) this Adds a layer into the given z-level
getAvailableZLevels() [Number] Returns a plain array of the z-levels which this z-demuxer has at least one layer in.
hasZLevel(<Number> zLevel) Boolean Returns true if this z-demuxer has at least one layer with the given z-level.