ambita-map.js
ambita-map.js is a Javascript API, it is built as a Leaflet wrapper or plugin.
Please refer to Leaflet documentation for further documentation on Leaflet.
ambita-map.js uses Leaflet 1.0.1 version which become a stable release just recently.
To get started
To get started you will need to include one CSS file and one JavaScript file in your HTML:
Include ambita-map CSS file in the <HEAD> section of the HTML:
<link rel="stylesheet" href="https://static.ambita.com/ambita-map/latest/ambita-map.css" />Include ambita-map JavaScript file in the <HEAD> or <BODY> section of the HTML:
<script src="https://static.ambita.com/ambita-map/latest/ambita-map.js"></script>Put a <div> with a given id where you want to show the map:
<div id="map"></div>And give the <div> a defined height, by CSS or property:
#map { height: 600px; }
See the style guide below on how to style the elements in the map.
Full example
<!DOCTYPE html>
<html>
<head lang="en">
<title>Ambita Map</title>
<link rel="stylesheet" href="https://static.ambita.com/ambita-map/latest/ambita-map.css" />
<style>
#map {
height: 600px;
}
</style>
</head>
<body>
<div id="map"></div>
<script src="https://static.ambita.com/ambita-map/latest/ambita-map.js"></script>
<script type="text/javascript">
var usedToken = "TOKEN";
var map = L.ambita.map("map", usedToken, {
center: [10, 60],
zoom: 14
});
</script>
</body>
</html>
The example of working with the map after initialization
To work with the created map object first it should be properly initialized, so every action on the map object should be done only after the ambitamap:loaded is fired.
map.on("ambitamap:loaded", function (event) {
// Work with the map object here
});
Demo
To see a complete demo of the ambita-map.js in action check out ambita-map.html
API
L.ambita.map(element | id, token, options)
Creates and configures the ambita-map.
Extends: L.Map
Factory
| Options | Type | Description |
|---|---|---|
element |
String | required Must be the id of an element, or a DOM element reference |
token |
String | required Token from the Ambita authenticaton API, if left empty, login window will be shown |
options |
Object | See below for options |
Options
| Option | Type | Default | Description |
|---|---|---|---|
restApi |
String | 'https://beta-api.ambita.com' | Realty REST API endpoint to query against, for production use https://api.ambita.com |
refreshToken |
String | ' ' | The refresh token used to refresh the access token to the map services, if left empty, nothing happens and tokenrequired event should be used |
crs |
CRS Object | L.ambita.CRS['EPSG:25833'] | The map CRS used to show base layer and other layers on the map in a different coordinate system than LatLng |
zoom |
Number | 14 | Sets the starting zoom level, valid levels between 1 and 17 |
center |
Number[] | [60, 10] | Sets the starting point, this is an array of two coordinates [latitude, longitude] |
keyboard |
Boolean | false | To allow of not the keyboard controlled movement of the map |
inertia |
Boolean | false | To enable or disable inertia when panning the map around with mouse |
attributionControl |
Boolean | false | To show or hide attribution control on the map |
attributionControlOptions |
Object | See below for options | Options to control the attribution control |
minZoom |
Number | 3 | To change the min zoom level of the map |
maxZoom |
Number | 17 | To change the max zoom level of the map |
ambitaToken |
String | undefined | To set the token from the Ambita authenticaton API using options (must set token to undefined on map init) |
geoToken |
String | undefined | To set a prefetched GeoData token (otherwise fetched by ambita-map automatically) |
maxRetries |
Number | 2 | To set the number of times tokenrequired is ignored on layer before firing map tokenrequired event |
svgPathClassName |
String | 'selection-cadastre' | To set the default SVG path class name |
detailedHeightLegendControl |
Boolean | true | To enable or disable the detailed height legend control |
fitBuffer |
Number | 10 | To set the buffer for fitBounds of points in pixels |
showControls |
Boolean | true | To show or hide all controls |
zoomControl |
Boolean | false | To show or hide the default Leaflet zoom control |
showPropertyLayer |
Boolean | true | To show or hide the property layer on the map |
fullscreenControl |
Boolean | false | To show or hide the default Leaflet fullscreen control |
layerControl |
Boolean | true | To show or hide the layer control button |
layerControlPosition |
String | 'topleft' | To set a different position of the layer control button |
layerControlHtml |
String | L.ambita.Statics.SVG_BUTTONS.layers | To set a custom html for Layers control button |
scaleControl |
Boolean | false | To show or hide the scale control at the bottom left corner of the map |
poweredByControl |
Boolean | true | To show or hide the Powered by Ambita control at the bottom right corner |
editable |
Boolean | false | To enable or disable the selection functionality on the map |
editOptions.lineGuideOptions.className |
String | 'selection-lineguide' | To set the class name of the selection tool line guide |
selectionToolsOptions |
Object | See below for options | Options to control the selection tools |
pocLayer |
Object | See below for options | Options to control the POC layer |
restrictToMunicipality |
String | undefined | To set a municipality code of which of the Norway municipality to fetch |
Methods
| Method | Returns | Description |
|---|---|---|
| showCadastre(<String> cadastre, <Object> options?) | map | Takes a cadastre string (knr/gnr/bnr) and marks it on the map, example: map.showCadastre('0301/1/1') |
| showMarkerLayer(<GeoJson> feature, <Object> options?) | map | Takes a GeoJson feature or featureCollection as input. The GeoJson can be either polygons, lines, points or any other valid GeoJson geometry. To set custom markers on icons use feature.properties.icon = icon, icon may be any font awesome icon https://fortawesome.github.io/Font-Awesome/icons/. To set a handler on clicking a feature use feature.properties.callback = callback where callback is a function |
The example use of map.showMarkerLayer
To show markers on the map call map.showMarkerLayer(features)
It is possible to have different types of actions when a feature are clicked in the map:
- run a callback function
- fire an event
- show a popup
To run a callback function
Set the callback parameter in properties
function clickPoint(feature) {
alert("Point clicked: " + feature);
}
var feature = {
type: "Feature",
properties: {
id: "123",
icon: "flag",
callback: clickPoint
},
geometry: {
type: "Point",
coordinates: [10, 60]
}
};
map.showMarkerLayer(feature);
To fire an event
Set the type parameter in properties, it will fire an featureClick event and passes the clicked feature
var feature = {
type: "Feature",
properties: {
id: "123",
icon: "flag",
type: "marker"
},
geometry: {
type: "Point",
coordinates: [10, 60]
}
};
map.showMarkerLayer(feature);
map.on("featureClick", function(event) {
doSomeThing(event);
});
To show a popup
Set the popup and the text parameters in properties
var feature = {
type: "Feature",
properties: {
id: "123",
icon: "flag",
popup: true,
text: "this is the text shown in the popup, it can be any valid text or html"
},
geometry: {
type: "Point",
coordinates: [10, 60]
}
};
map.showMarkerLayer(feature);
Attribution control options
| Option | Type | Default | Description |
|---|---|---|---|
position |
String | 'bottomright' | To set a different position of the attribution control |
prefix |
String | ' ' | To set a different prefix text to the attribution control |
POC layer options
| Option | Type | Default | Description |
|---|---|---|---|
options |
Object | An Object containing all the POC layer options | |
options.on |
Boolean | true | To enable and disable the POC layer |
options.minZoom |
Number | 13 | To set the min zoom of when the POC layer is visible |
Selection tools options
| Option | Type | Default | Description |
|---|---|---|---|
position |
String | 'bottomleft' | To set a different position of the selection tools control |
fitToFeatureOwnerList |
Boolean | false | To enable or disable fitBounds to owner list |
fitToFeatureNeighborList |
Boolean | true | To enable or disable fitBounds to neighbor list |
filterSectionOwnerList |
Boolean | false | To enable or disable filter on sections in owner list |
filterSectionNeighborList |
Boolean | false | To enable or disable filter on section in neighbor list |
mainCadastreNameNeighborList |
String | 'selection-main-cadastre' | To set the neighbor list main cadastre name |
maxOwnerListCount |
Number | 500 | To set the max owner list count returned from service |
maxNeighborListCount |
Number | 35 | To set the max neighbor list count returned from service |
minPolygonAreaSize |
Number | 100 | To set the min area size of Polygon selection |
minRectangleAreaSize |
Number | 100 | To set the min area size of Rectangle selection |
intersectingPolygonErrorTooltip |
String | 'Linjene kan ikke krysses' | To set a different tooltip for the intersectiing polygon error |
maxOwnerListCountErrorTooltip |
String | 'Ingen flere matrikkler kan legges til utvalget' | To set a different tooltip for the max owner list count error |
maxOwnerListSelectionCountErrorTooltip |
String | 'Valgt område er for stort, for mange eiendommer returnert' | To set a different tooltip for the max owner list selection count error |
maxNeighborListCountErrorTooltip |
String | 'Ingen flere matrikkler kan legges til utvalget' | To set a different tooltip for the max neighbor list count error |
mainCadastreNeighborListErrorTooltip |
String | 'Hoved matrikkelen finnes ikke, så det er ingen nabo listen tilgjengelig' | To set a different tooltip for the main cadastre neighbor list error |
minPolygonAreaSizeErrorTooltip |
String | 'Valgt område er for lite' | To set a different tooltip for the min area size error for Polygon |
minRectangleAreaSizeErrorTooltip |
String | 'Valgt område er for lite' | To set a different tooltip for the min area size error for Rectangle |
maxPolygonAreaSizeErrorTooltip |
String | 'Valgt område er for stort' | To set a different tooltip for the max area size error for Polygon |
maxRectangleAreaSizeErrorTooltip |
String | 'Valgt område er for stort' | To set a different tooltip for the max area size error for Rectangle |
outsideNorwayErrorTooltip |
String | 'Utvalget har gjort må være helt inne Norge' | To set a different tooltip for the selection outside of Norway error |
intersectionWithOsloErrorTooltip |
String | 'Utvalget må være enten helt innenfor eller utenfor Oslo' | To set a different tooltip for the selection intersecting with Oslo error |
cadastreToggleButtonIcon |
String | 'fa-mouse-pointer' | To set a different Font Awesome icon for the cadastre toggle button |
cadastreToggleButtonTitle |
String | 'Legg til eller fjern matrikkel fra utvalget' | To set a different title for the cadastre toggle button |
cadastreToggleTooltip |
String | 'Klikk på kartet for å legge til en matrikkel, klikk på en matrikkel for å fjerne den' | To set a different tooltip for the cadastre toggle button |
polylineButtonIcon |
String | 'fa-expand' | To set a different Font Awesome icon for the polyline button |
polylineButtonHtml |
String | L.ambita.Statics.SVG_BUTTONS.polyline | To set a different html for the polyline button |
polylineButtonTitle |
String | 'Tegn en linje' | To set a different title for the polyline button |
polylineStartTooltip |
String | 'Klikk i kartet for å starte en linje' | To set a different tooltip for the polyline start point |
polylineContinueTooltip |
String | 'Klikk i kartet for å skifte retning' | To set a different tooltip for the polyline continue point |
polylineFinishTooltip |
String | 'Klikk på det siste punktet for å avslutte linjen' | To set a different tooltip for the polyline finish point |
polygonButtonIcon |
String | 'fa-map' | To set a different Font Awesome icon for the polygon button |
polygonButtonHtml |
String | L.ambita.Statics.SVG_BUTTONS.polygon | To set a different html for the polygon button |
polygonButtonTitle |
String | 'Tegn et polygon' | To set a different title for the polygon button |
polygonStartTooltip |
String | 'Klikk i kartet for å starte polygonet' | To set a different tooltip for the polygon start point |
polygonContinueTooltip |
String | 'Klikk i kartet for å fortsette polygonet' | To set a different tooltip for the polygon continue point |
polygonFinishTooltip |
String | 'Klikk på det siste punktet for å avslutte polygonet' | To set a different tooltip for the polygon finish point |
rectangleButtonIcon |
String | 'fa-stop' | To set a different Font Awesome icon for the rectangle button |
rectangleButtonHtml |
String | L.ambita.Statics.SVG_BUTTONS.rectangle | To set a different html for the rectangle button |
rectangleButtonTitle |
String | 'Tegn et rektangel' | To set a different title for the rectangle button |
rectangleStartTooltip |
String | 'Trykk og dra i kartet for å starte rektangelet' | To set a different tooltip for the rectangle start point |
rectangleFinishTooltip |
String | 'Dra i hjørnet eller klikk på det for å fullføre rektangelet' | To set a different tooltip for the rectangle finish point |
deleteButtonIcon |
String | 'fa-trash' | To set a different Font Awesome icon for the delete button |
deleteButtonTitle |
String | 'Slett utvalget' | To set a different title for the delete button |
dragVertexTooltip |
String | 'Dra i et punkt for å endre' | To set a different tooltip for the vertex drag for rectangle |
dragClickVertexTooltip |
String | 'Dra i et punkt for å endre eller klikk for å slette det' | To set a different tooltip for the vertex drag or click for polyline and polygon |
Selection tools events
| Event | Description | Returned value |
|---|---|---|
selection:started |
Event is fired when a new drawing is started | Event returns the type of drawing editor that is started |
selection:ended |
Event is fired when the drawing is ended using mouse double click | Event returns the GeoJSON of the selection made on the map |
selection:updated |
Event is fired when the drawing is modified using mouse | Event returns the GeoJSON of the selection made on the map |
selection:updating |
Event is fired when the drawing is started to be modified using mouse | Event returns the GeoJSON of the selection made on the map |
selection:deleted |
Event is fired when the drawing is deleted | Event does not return any data |
ownerlist:cleared |
Event is fired when the owner list is cleared | Event does not return any data |
neighborlist:cleared |
Event is fired when the neighbor list is cleared | Event does not return any data |
ownerlist:updated |
Event is fired when the owner list is updated | Event returns data containing the GeoJSON of the selection made on the map and selected cadastres |
neighborlist:updated |
Event is fired when the neighbor list is updated | Event returns data containing the GeoJSON of the selection made on the map, selected cadastres and neighbor list selected plot |
ownerlist:deleted |
Event is fired when the owner list is deleted | Event does not return any data |
neighborlist:deleted |
Event is fired when the neighbor list is deleted | Event does not return any data |
neighborlist:mainplotselected |
Event is fired when the main plot is selected for the neighbor list | Event returns data containing feature layer of the selected plot |
neighborlist:mainplotsreset |
Event is fired when the main plot is reset for the neighbor list | Event does not return any data |
The example use of selection tools events
Selection tools fire events so the user can act on them to do different actions on the map based on the event.
The example JavaScript code for use of selection tools events using the already created map instance is shown below:
map.on("selection:updated", function (event) {
// Use the event here
});
Token handling
To use the map you will be provided with credentials to generate tokens at https://api.ambita.com/authentication/v2/token.
When you make a token request you will get a JSON reply like this:
{
"access_token": "b8e7f3c5-f8c6-4011-9bd6-0282a1894df7",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "8fbb98e3-2bb4-4824-bcde-e16210e0a79d",
"scope": [
"authentication.geodatatoken"
]
}
Where you will pass the access_token to the map initialization function. When the token expires the map will fire a tokenrequired event.
You will then have to provide a new or refreshed token back.
Token example code
var getTokenFunction = function(map) {
/* code to get token */
map.authenticate(token);
}
var map = L.ambita.map("map", token, {
center: [10, 60],
zoom: 14
}).on("tokenrequired", function () {
getTokenFunction(map);
});
Styling elements
It is possible to style the different elements (buttons and controls) in the map
| Identifier | Description |
|---|---|
| .leaflet-bar a | Style for buttons and controls |
| .leaflet-bar a:hover | Style for buttons and controls on hovering |
| .leaflet-bar .leaflet-control-zoom-in | Zoom control |
Example stylesheet
.leaflet-bar a {
width: 36px;
height: 36px;
line-height: 36px;
color: #ffffff;
background-color: #0078c8;
}
.leaflet-bar .leaflet-control-zoom-in {
color: #0078c8;
background-color: #ffffff;
}
.leaflet-bar a:hover {
width: 36px;
height: 36px;
line-height: 36px;
}
.leaflet-top.leaflet-left {
margin-top: 0 !important;
}
Versioning
Stable releases will be available here: https://static.ambita.com/ambita-map/
Beta releases will be available here: https://beta-static.ambita.com/ambita-map/
The latest stable release will always be available here: https://static.ambita.com/ambita-map/latest/
Be aware of caching in the browser when using: https://static.ambita.com/ambita-map/latest/
To break caching you can put a random query after the path: https://static.ambita.com/ambita-map/latest/ambita-map.js?randomText