Skip to content

Create map tech package

Jump to bottom
IlianSchokkaert edited this page Jul 7, 2016 · 7 revisions

This guide explains how to create a new map technology package to plug into the GNaP Map library.

Package structure

Your package should have the following structure:

gnap-map-<techname>
 |_ dist: All custom js and css files concatenated, both unminified and minified, and img files.
 |   |_ gnap-map-<techname>.js
 |   |_ gnap-map-<techname>.min.js
 |   |_ gnap-map-<techname>.css: Optional: any additional css.
 |   |_ gnap-map-<techname>.min.css: Optional: any additional css, minified
 |_ src: The sources for your package.
 |   |_ js: Javascript sources
 |   |   |_ map-tech-<techname>.js: The main module file of your map technology (see below).
 |   |   |_ map-view-<techname>.directive.js: The actual map view directive (see below).
 |   |_ css: Optionally add any additional css
 |   |   |_ gnap-map-<techname>.css: Optional: any additional css.
 |   |_ img: Any additional images
 |_ Gruntfile.js: The 'grunt dist' command should produce all files in the 'dist' folder.
 |_ package.json
 |_ README.md

For an example of the map-tech service, map-view directive and Gruntfile you can have a look at the ones for the Google Map Tech package.

Map technology service

The map technology service creates the module, defines the technology, specifies a default style function, registers itself on the main GNaP map library's mapTechProvider and optionally adds any additional behavior to the service, which can be used from within the directive.

Map technology definition

Each map technology must be defined by an object with the following properties, and register itself using these by calling mapTechProvider.registerMapTech(mapTechDefinitionObject). This object must contain the following properties:

  • key: The (camelCase) key of the map technology. Must be unique.
  • displayName: The (currently not translatable) display name of this map technology; used in the map tech selector.
  • coordinateSystem: The coordinate system that the map view expects. All GeoJson returned from the server should be provided in this system. If it differs from the default coordinate system, it will be passed as a query string parameter to all calls to the backend server as ?result=<system>.
  • defaults: Default initialization properties for the map view. These are typically overridden / set in the config block of the application (in the setDefaults function on this technology's provider), but if not, these values are used.
    • zoomLevel: The default map-view-specific view level the map should start on. Note that this is currently not necessarily in the 0-10 scale which the is used elsewhere in the application.
    • center: The default ma-view-specific position the map should start on. This should be in whatever format the map view can work with; typically an object containing a latitude and longitude coordinate.
    • defaultStyleFunction: the default map-view-specific styling function to use for all features. Used for any layer which does not specify its own function.

Registration and configurability

In the provider, the technology package should register itself on the GNaP Map main library's mapTechProvider by injecting this and calling mapTechProvider.registerMapTech(mapTechDefinitionObject).

Aside from this, the provider must expose the following setDefaults function:

this.setDefaults = function (options) { angular.extend(mapTechDefinitionObject.defaults, options); };

This allows any of the options/defaults to be overridden during the config phase of this map technology in the main application.

Other than this required function, the map tech provider may expose any other function which may be called during the config phase. This should be well-documented, however. For an example, see the setStyles function of the Google map technology package.

Map view directive

The actual directive which shows this technology's map view, adds and removes GeoJson data and possibly other types of data and interacts with the map manager.

Its template must be a div with its width and height set to 100%.

It accepts one optional directive parameter: activateDrawingMode, which specifies whether or not the drawing toolset is available to the user.

The main GNaP Map's map manager and a specific technology's map view are tied together through a number of 'action functions' which are publicly available on the map manager, which the map view must supply the implementation for. Switching to a map technology lets this technology implement/override these functions. This happens at link time of the directive. Henceforth, whenever either the map manager himself, or anyone who gets the map manager injected, calls any of these 'map view' or 'viewport' related actions, they are delegated to the map view.

Not all functions are required - some are optional. If an optional function is not supplied, that functionality will simply not be available. The application will log this, and in code, you have the ability to check whether a function is implemented by the currently selected map view technology by calling mapManager.mapFunctionIsSupported(mapManager.mapView.<functionToCheck>).

The map view functions which must or can be implemented are described below. Don't forget to check the example implementation in the Google Map Tech plugin.

Map view functions

addCustomKml and removeCustomKml

Optional. Not called by the map manager itself. Since different map technologies have different ways of adding and removing kml layers, the parameters to and implementation of this function can differ greatly. In the Google Map Tech plugin, kml layers are added as fusion tables. This function accepts an object with the following properties:

  • layerId: the id of a fusion table
  • clickable: whether or not the layer should be clickable

showInfoWindow and closeInfoWindow

Optional. Not directly called by the map manager - should be called upon entering and leaving the main.map.info state. Implementation can be map view specific. The Google Map Tech implementation accepts two parameters: the position as a {lat, lng} object literal, and an optional content.

resizeMap

Optional. Not called by the map manager. Can be called, typically by the map controller, when the div or the browser window gets resized, to inform the map view. Called without argument.

activateDrawingMode

Optional. Not called by the map manager. Activates a drawing tool on the map view. When the user completes the action, the map view must emit call mapManager.events.onCustomShapeCreated(wkt, removeFunction) with two parameters: first, the drawn shape as wkt and second, a callback function to remove the drawn shape, if desired, after the user accepts the completion of the drawing or cancels it. The callback function does not expect any arguments.

getGeoJson

Optional async function. Not called by the map manager. Typically called by the map controller. Should return a promise which is resolved with the geoJson that is currently visible in the viewport.

Viewport functions

getZoomLevel and setZoomLevel

Required; used by the map manager. accept and return the zoom level as an integer on a scale of 0-10; typically translate this to a value the map technology can work with.

getCenter, getCenterWgs84, setCenter and setCenterWgs84

Optional. Not called by the map manager. The Wgs84-variants accept or return the center in WGS 84 (gps) coordinates, the other functions accept or return the center in the map technology's own coordinate system.

Note: setCenterWgs84 is used by the Google Map Tech's search box.

getBounds, getBoundsWgs84, setBounds and setBoundsWgs84

getBoundsWgs84 and getBoundsWgs84 is required, the setters are optional. The Wgs84-variants accept or return the center in WGS 84 (gps) coordinates, the other functions accept or return the center in the map technology's own coordinate system.
getBoundsWgs84 is used by the map manager to pass on to the map geo data service, to pass the viewport's bounds to the back-end service (unless all data is cached). getBounds is used by the mapManager's internals to determine whether or not a feature has already been added to the current viewport.

Note: setBoundsWgs84 is used by the Google Map Tech's search box.

isInBounds, containsBounds, containsCoordinate

isInBounds and containsCoordinate are required (used by the map manager's internals), containsBounds is not. Coordinates are in the map technology's coordinate system.

Add / remove GeoJson / centerOnFeature functions

Both are required and the core of the map view technology. They get called by the map manager when necessary, they should never be called manually and are hence to be considered private.

_addGeoJsonData

This function accepts three parameters:

  • geoJsonData (object): should contain a features property, which is an array with the features to be added. All features should be of only one type, as specified by the second parameter:
  • featureType (string): the itemType of the passed geoJsonData.
  • redraw (bool): when truthy value is passed, all features in the passed geoJsonData should be redrawn; not only those which have not yet been drawn.

Note: this function is at the core of the GNaP Map plugin. It should be very efficient.

The map manager expects the following behavior from this function:

  • As mentioned here, all GeoJson features must have a unique id.
  • Ideally, if the feature with this id has already been added to the map, it should not be redrawn if the redraw parameter is not truthy, both to avoid flickering, and to improve performance.
  • If the redraw parameter is truthy, the feature will be redrawn: the new visualization replaces the old one.
  • If the layer has a getLabelStyleFunction or if a label property exists on the feature's custom properties, this function should also add these labels. Because labels will generally depend on the zoom level, labels should likely always be redrawn!

_removeGeoJsonData

This function accepts one parameter: the item type, as a string, of the layer to clear. Note that if that layer contains labels, this function is also responsible to clear these.

Note: this function is also called very often and should be very efficient.

_centerOnFeature

This function accepts one parameter: a feature. A feature should contain a geometry object which contains an array of coordinates.

Clone this wiki locally