20.04.2017 - New in V0.3.3: All methods return now a
Promise
object in addition to calling the callback function. This makes programming easier as you can use
then
or
await
control structures.
"easyGuide maps engine" is a lightweight JavaScript library that allows external developers to easily add an interactive map to their web application with just a few lines of code. "EasyGuide maps" are in particular geared to allow navigation and orientation within buildings. Native app developers (Java, Swift, Objective-C, etc.) can also take advantage of this library via the common WebView components using the two-way JavaScript Interface. For "easyGuide maps engine" to work an internet connection is required. The one-time heavy-lifting setup to add a particular building is done by the service provider (= us) and hidden from the service consumer (= you).
The following documentation describes the Open API of the "easyGuide maps engine" in detail allowing developers to easily integrate it in their own applications. Follow this link for a high-level overview of the overall functionalities.
# | Return (async) | Method | Test | Documentation |
---|---|---|---|---|
1 | = EasyGuideMapsEngine.toString(); | |||
2 | = EasyGuideMapsEngine.refresh(); | |||
3 | = EasyGuideMapsEngine.reset(); | |||
4 | = EasyGuideMapsEngine.screenshot(); | |||
5 | = EasyGuideMapsEngine.retrieve( ); | |||
6 | = EasyGuideMapsEngine.retrieveClosestElementsByCoordinates([ , ], )); | |||
7 | = EasyGuideMapsEngine.get( ); | |||
8 | = EasyGuideMapsEngine.set( , ); | |||
9 | = EasyGuideMapsEngine.route([ , ], ); | |||
10 | = EasyGuideMapsEngine.focus( , , ); | |||
11 | = EasyGuideMapsEngine.highlight([ ], , , ); | |||
12 | = EasyGuideMapsEngine.popup( , , ); | |||
The "easyGuide maps engine" uses
Semantic Versioning. The version number
MAJOR.MINOR.PATCH
changes as follows:
EasyGuideMapsEngine.toString()
returns the current name and version number of the "easyGuide maps engine" library.
Include the easyGuide maps engine JavaScript file in the header and add a
<div>
-container with an id to the body where you want the map to be displayed.
<!DOCTYPE html> <html> <head> <title>easyGuide maps engine - Example</title> <script type="text/javascript" src="https://engine.easy-guide.com/EasyGuideMapsEngine_V0.3.3.min.js"></script> <script type="text/javascript" src="MyScript.js"></script> </head> <body> <div id="divMap" style="width:400px;height:300px;background-color:#C0C0C0;">Loading...</div> </body> </html>
Create a new
EasyGuideMapsEngine
instance in your JavaScript code after the DOM content has been loaded.
Options:
debug: boolean (optional)
: Enable or disable debug mode. In debug mode the ids of elements are displayed on the map and additional
output in printed to the browser console. Default value is false.
project: number
: The six-digit unique project id defined by the service provider.
key: string
: The individual project API license key - use "demo" for testing purposes.
container: string
: The id of the <div> element, where you want the map to be displayed. Any other content in the
<div> element will be removed.
window.document.addEventListener("DOMContentLoaded", function() { var oEasyGuideMapsEngineOptions = { "debug": false, "project": 100025, "key": "demo", "container": "divMap" }; var oEasyGuideMapsEngine = new EasyGuideMapsEngine(oEasyGuideMapsEngineOptions); });
You can enable/disable specific build-in controls via the
controls: object
parameter of the options object literal.
window.document.addEventListener("DOMContentLoaded", function() { var oEasyGuideMapsEngineOptions = { "debug": false, "project": 100025, "key": "demo", "container": "divMap", "controls": { "attribution": true, "zoom": true, "rotation": true, "scaleline": true, "layer": true, "route": true } }; var oEasyGuideMapsEngine = new EasyGuideMapsEngine(oEasyGuideMapsEngineOptions); });
Each control can be enabled/disabled individually.
# | control | value | description |
---|---|---|---|
1 | attribution | bEnable: boolean | Displays a little 'i'nfo-icon with copyright information. If disable the information is permanently displayed in the lower right corner. |
2 | zoom | bEnable: boolean | Displays a zoom in/out control. |
3 | rotation | bEnable: boolean | Displays a rotation/heading indicator control. Activating the control will align the map to the north. |
4 | scaleline | bEnable: boolean | Displays a true-to-scale distance indicator control. |
5 | layer | bEnable: boolean | Displays a layer control allowing the user to switch between floors. |
6 | route | bEnable: boolean | Displays a route control with a step-by-step navigation for each route section. When enabled the control is only visible if a route is currently displayed on the map. |
You can register a function to listen to events triggered by the map via the
callback: function
parameter of the options object literal.
window.document.addEventListener("DOMContentLoaded", function() { var oEasyGuideMapsEngineOptions = { "debug": false, "project": 100025, "key": "demo", "container": "divMap", "controls": {"attribution": true, "zoom": true, "rotation": true, "scaleline": true, "layer": true, "route": true}, "callback": onMapEvent }; var oEasyGuideMapsEngine = new EasyGuideMapsEngine(oEasyGuideMapsEngineOptions); });
The event listener function is passed an event with an
id: string
property to identify the type of event and a variant number of properties depending on the event type.
# | id | trigger | properties |
---|---|---|---|
1 | EasyGuideMapsEngine.EVENT_LOADED | Fired when the instance has loaded | info: string |
2 | EasyGuideMapsEngine.EVENT_TARGET_SELECTED | Fired when the user has selected an element (highlighter, icon or point) on the map | type: string, target: string, position: number[] |
3 | EasyGuideMapsEngine.EVENT_LAYER_CHANGED | Fired when the user or an engine event triggerd a layer change | layer: string, formerLayer: string |
4 | EasyGuideMapsEngine.EVENT_FUNCTION_RETURN | Fired when the return value of a previously executed EasyGuideMapsEngine function call is returned asynchronous | functionName: string, functionArguments: any[], returnValue: any |
function onMapEvent (oEvent) { switch (oEvent.id) { case EasyGuideMapsEngine.EVENT_LOADED: // the instance has loaded console.log(oEvent.info + " loaded"); break; case EasyGuideMapsEngine.EVENT_TARGET_SELECTED: // the user has selected an element (highlighter, icon or point) on the map console.log(oEvent.type + " \"" + oEvent.target + "\" selected" + " (longitude: " + oEvent.coordinates.longitude.toFixed(6) + ", latitude: " + oEvent.coordinates.latitude.toFixed(6) + ")"); break; case EasyGuideMapsEngine.EVENT_LAYER_CHANGED: // the user or an engine event triggerd a layer change console.log("Layer changed from " + oEvent.formerLayer + " to " + oEvent.layer); break; case EasyGuideMapsEngine.EVENT_FUNCTION_RETURN: // the return value of a previously executed EasyGuideMapsEngine function call is returned asynchronous console.log("EasyGuideMapsEngine." + oEvent.functionName + "(" + oEvent.functionArguments.join(", ") + ") return callback value is\"" + oEvent.returnValue + + "\""); break; default: console.warn("Unknown map event " + oEvent.id); break; } }
All EasyGuideMapsEngine asynchronous methods return a Promise object.
oEasyGuideMapsEngine.get("zoom").then(function(nZoom) { console.log(nZoom); });or
async function printLayer() { var sLayerId = await oEasyGuideMapsEngine.get("layer"); console.log(sLayerId); } printLayer();
In addition the callback (if set) will be called with the event-id
EasyGuideMapsEngine.EVENT_FUNCTION_RETURN
and the properties
functionName: string
,
functionArguments: any[]
and
returnValue: any
.
The method
EasyGuideMapsEngine.toString(): string
returns the name and version number of the easyGuide maps engine library.
Returns
(async):
sClassName: string
: Returns the class name with version number.
Example:
console.log(oEasyGuideMapsEngine.toString()); // "EasyGuide maps engine V#.#.#"
The method
EasyGuideMapsEngine.refresh(): void
forces a map re-rendering of the map. This can be necessary if the size of the parent
<div>
container is changed and distortions are encountered.
Returns (async):
bSuccess: boolean
: A flag to indicate the success of the function call.
Example:
oEasyGuideMapsEngine.refresh(); // refresh the map
The method
EasyGuideMapsEngine.reset(): void
resets the map to the initial viewport without changing the current layer.
Returns (async):
bSuccess: boolean
: A flag to indicate the success of the function call.
Example:
oEasyGuideMapsEngine.reset(); // center the map
The method
EasyGuideMapsEngine.screenshot(): void
creates a screenshot of the current viewport without controls.
Returns (async):
oScreenshot: HTMLImageElement
: An image object with width, height and src properties.
Example:
oEasyGuideMapsEngine.screenshot(); // take a screenshot of current viewport
The method
EasyGuideMapsEngine.retrieve(sElementType: string): void
retrieves a list of ids for the given element type.
Arguments:
sElementType: string
: The type ("layers"|"highlighters"|"points"|"icons") of element to retrieve.
# | type | format (regex) | description |
---|---|---|---|
1 | layers | L[0-9]{2} | The list of layers (= floors / level) of the building |
2 | highlighters | L[0-9]{2}P[0-9]{4} | The list of selectable surfaces |
3 | points | L[0-9]{2}P[0-9]{4} | The list of route point |
4 | icons | L[0-9]{2}P[0-9]{4} | The list of icons |
Returns (async):
oElementsIdsList: string[]
: The list of ids for the given element type.
Example:
oEasyGuideMapsEngine.retrieve("layers"); // [L01, L02, L03, L04, L05]
The method
EasyGuideMapsEngine.retrieveClosestElementsByCoordinates(oLongitudeLatitudeCoordinates: number[], sLayerId: string): void
retrieves a list of the three closest elements within the given layer for the given geo-coordinates in the
commonly used
WGS (= EPSG:4326) format.
Arguments:
oLongitudeLatitudeCoordinates: number[]
: The geo-coordinates ([longitude: number, latitude: number])
sLayerId: string
: The layer id (default: current layer)
Returns (async):
oClosestElementsIdsList: string[]
: The list of point ids closest to the given coordinates.
Example:
oEasyGuideMapsEngine.retrieveClosestElementsByCoordinates([24.81077805, 60.21808025], "L03"); // [L03P1216, L03P1217, L03P1215]
The method
EasyGuideMapsEngine.get(sSettingKey: string): void
gets the value of a specific setting.
Arguments:
sSettingKey: string
: The setting key ("zoom"|"rotation"|"layer"|"start"|"end"|"section").
# | key | value | description |
---|---|---|---|
1 | zoom | nZoom: number | Gets the current zoom level of the map with values between 0 (= min) and 1 (= max). There are 8 zoom levels, thus the zoom step size is 1 / 8 = 0.125. |
2 | rotation | nRotation: number | Gets the current rotation of the map in radian with values between 0 and 2π (= 6.28318530718) |
3 | layer | sLayerId: string | Gets the current layer of the map. |
4 | start | sPointId: string | Gets the current start marker (red) of the map. Returns
null if the start marker is currently not set. |
5 | end | sPointId: string | Gets the current end marker (black) of the map. Returns
null if the end marker is currently not set. |
6 | section | nSectionIndex: number | Gets the current route section. Returns
null if a route is currently not set. |
Returns (async):
sSettingValue: any
: The current setting value.
Example:
oEasyGuideMapsEngine.get("zoom"); // 1 = maximum zoom level
The method
EasyGuideMapsEngine.set(sSettingKey: string, sSettingValue: string): void
sets the value of a specific setting.
Arguments:
sSettingKey: string
: The setting key ("zoom"|"rotation"|"layer"|"start"|"end"|"section").
sSettingValue: string
: The setting value.
# | key | value | description |
---|---|---|---|
1 | zoom | nZoom: number | Sets the zoom level of the map with values between 0 (= min) and 1 (= max). The minimum zoom step size is 1 / 8 = 0.125. |
2 | rotation | nRotation: number | Sets the rotation of the map in radian with values between 0 and 2π (= 6.28318530718) |
3 | layer | sLayerId: string | Sets the layer of the map. The list of supported layers can be retrieved via
oEasyGuideMapsEngine.retrieve("layers")
|
4 | start | sPointId: string | Sets the start marker (red) of the map. The list of supported points can be retrieved via
oEasyGuideMapsEngine.retrieve("points")
|
5 | end | sPointId: string | Sets the end marker (black) of the map. The list of supported points can be retrieved via
oEasyGuideMapsEngine.retrieve("points")
|
6 | section | nSectionIndex: number | Sets the route section and focuses the map on it. Valid valus are integer values from 0 (= first route section) to oRouteLayersIdsList.length-1 (= last route section) |
Returns (async):
sNewSettingValue: any
: The new current setting value.
Example:
oEasyGuideMapsEngine.set("layer", "L01"); // switch to layer L01
The method
EasyGuideMapsEngine.route(oWayPointsIdsList: string[], bAccessible?: boolean=false): void
displays a route on the map. A previously displayed route is removed if required.
The map is NOT automatically switched to the layer of the given start point. Use
EasyGuideMapsEngine.set("section", 0)
to focus on the first route section.
Arguments:
oWayPointsIdsList: [sStartPointId: string, sEndPointId: string]
: The start and end point. Pass
null
to remove an existing route.
bAccessible: boolean (optional)
: The flag to use an alternative accessible route avoiding stairs, escalators or similar obstacles. Default
value is false.
Returns (async):
{
distance: number,
duration: number,
layers: string[]
}
: The object literal with the route distance (in meter), duration (in seconds) and associated layers.
Example:
oEasyGuideMapsEngine.route(["L02P2013", "L04P2146"], true); // display the accessible route from point L02P2013 to L04P2146
The method
EasyGuideMapsEngine.focus(sElementId: string, nZoom?: number=<current zoom>, nAnimationDuration?: number=2): void
centers the map over a given element. If required the layer is switched automatically to the layer of the
target element.
Arguments:
sElementId: string
: The element to focus on.
nZoom: number (optional)
: The target zoom level between 0 (= min) and 1 (= max). Default value is the current zoom level.
nAnimationDuration: number (optional)
: The target animation duration in seconds between 0 (= instant change) and 10 (= ten seconds animation).
Default value is a 2 seconds animation.
Returns (async):
bSuccess: boolean
: A flag to indicate the success of the function.
Example:
oEasyGuideMapsEngine.focus("L03P2273", 1, 3); // maximum zoom on element L03P2273 within 3 seconds animation
The method
EasyGuideMapsEngine.highlight(oElementsToHighlightIdsList: string[], sFillColor: string, sStrokeColor: string, sHighlightMode: string): void
highlights elements on the map.
Arguments:
oElementsToHighlightIdsList: string[]
: The list of elements to set, add or remove. Pass
null
to remove all current highlighters.
sFillColor: string
: The fill color for the element. Valid values are any CSS color code. For no-fill pass
null
.
sStrokeColor: string
: The stroke color for the element. Valid values are any CSS color code. For no-stroke pass
null
.
sHighlightMode: string
: The mode (EasyGuideMapsEngine.HIGHLIGHT_SET, EasyGuideMapsEngine.HIGHLIGHT_ADD or EasyGuideMapsEngine.HIGHLIGHT_REMOVE).
Returns (async):
oElementsCurrentlyHighlightedIdsList: string[]
: The list of ids of currently highlighted elements.
Example:
oEasyGuideMapsEngine.highlight(["L02P2061", "L03P2273"], "rgba(255, 0, 0, 0.5)", "#000000", EasyGuideMapsEngine.HIGHLIGHT_SET); // highlight surface L02P2061 & L03P2273 with a semi-transparent red filling and a black border
The method
EasyGuideMapsEngine.popup(sElementId: string, sHtml: string, bShowCloseButton?: boolean): void
displays a popup above the given element.
Arguments:
sElementId: string
: The element above which the popup shall be displayed. Pass
null
to remove a currently visible popup.
sHtml: string
: The HTML content to display.
bShowCloseButton: boolean
: The flag to show or hide the closing-✖ button at the top right corner.
Returns (async):
bSuccess: boolean
: A flag to indicate the success of the function.
Example:
oEasyGuideMapsEngine.popup("L02P2061", "<video controls style='width:272px;height:153px;' src='http://cdn.guide3d.com/videos/100013/544x306/L03P1000-L04P1165-M0110.mp4'/>", true); // display a popup with a video player above point L02P2061
You can download here this documentation including a simple one file example for you to upload on any webserver for testing purposes.