Plugins

Plugins can be used to extend the functionality of the mapp and mapp.ui libraries.

Plugins are modules which export as default an IIFE (Immediately Invoked Function Expression).

Within the IIFE a plugin can be assigned to the mapp.plugins object extend or replace methods in lookup objects such as mapp.ui.locations.entries.

export default (function(){

 // This plugin will be called if the locale has the hide_layers key.
 mapp.plugins.hide_layers = (options, mapview) => {
  // hide_layers script
 }

 // This plugin will be called if a layer with the compare_locations key is decorated.
 mapp.plugins.compare_locations = layer => {
  // compare_locations script
 }

 // A custom panel script will be added to the mapp.ui.layers.panels
 mapp.ui.layers.panels.cluster_panel = layer => {
  // cluster_panel script
 }

})()

Loading plugins

Plugins are loaded as dynamic imports. The loadPlugins util will attempt to import modules from an array of resource locators.

"plugins": [
 "${PLUGINS}/js/plugins/cluster_panel.js",
 "${PLUGINS}/js/plugins/measure_distance.js",
 "${PLUGINS}/js/plugins/draw_circle_element.js"
]

The default view script will load all modules from the locale plugins array.

await mapp.utils.loadPlugins(locale.plugins);

Object.keys(locale).forEach((key) => {
 mapp.plugins[key] && mapp.plugins[key](locale[key], mapview);
});

Layer plugins

The mapp.layer.decorate method will check whether any keys on the layer match a mapp.plugins method and call that method with layer as only argument. Configuration for these plugins should be as an object assigned to the key. For example a plugin to measure distances may have a configuration object with information in regards to the units of measurement. However, the JSON layer is provided as only argument to the plugin method and hence any layer configuration is available to the plugin.

"measure_distance": {
 "tooltip": "length",
 "units": "metric",
 "hereRoute": "pedestrian" // or "car"
}

The layer view does not exist when a layer is decorated. Layer views are created by the mapp.ui library. A layer view plugin should be assigned to mapp.ui.layers.panels. The plugin method will be called with layer as argument from the layer view creation method.

Location plugins

Location plugins should be assigned to mapp.ui.locations.entries. The entry which has a location and associated layer as argument will be passed with any custom configuration to the entries plugin method.

Core plugins

Core plugins are selection of common plugins provided with the XYZ repository in the public directory.

cluster_panel

The cluster_panel plugin adds the cluster_panel to mapp.ui.layers.panels.

If configured in the layer configuration a panel will be added to the layer view.

"cluster_panel": true

compare_locations

The compare_locations plugin will be called if a layer has a compare_locations object configuration.

A fields array is required for the plugin. The title value is used for the first column in a comparison table.

A tab will be created in a tabview if the tabview target is configured and found.

The tab will be displayed when the display flag is set as true.

"compare_locations": {
 "target": "tabview",
 "display": true,
 "fields": [
  {
   "field": "rp_name",
   "title": "Name"
  },
  {
   "field": "rp_type",
   "title": "Type"
  },
  {
   "field": "classbrass",
   "title": "Class/Brass"
  }
 ]
}

A map object is assigned to the compare_locations object. The map stores location values with their key layer|id

The add_location method requires a location with a hook value as key. Matching infoj values will be mapped to the fields array and stored in the compare_locations.map.

The remove_key method requires a location key and will remove that key and associated values from the compare_locations.map.

The draw_callback is called after a location is added or removed from the compare_locations.map.

Object.assign(layer.compare_locations,{
 map: new Map(),
 add_location,
 remove_key,
 draw_callback: drawTable
})

The default callback is drawing a table in the tab panel.

A add_to_comparison method will be added to mapp.ui.locations.entries. If defined a type entry in the layer's infoj array a button will be returned from the entry method. The button will call the add_location method with the entry's location as argument.

"infoj": [
 {
  "type": "add_to_comparison"
 }
]

draw_circle_element

The draw_circle_element plugin adds the circle_from_center method to mapp.ui.elements.drawing. If defined in the layers edit object, a draw circle from center control will be added to the draw panel of a location view. It is possible to define the default unit and value.

"edit": {
 "circle_from_center": {
  "units": "km",
  "radius": 500
 }
}

hide_layers

The hide_layers plugin adds a button to the btn column in the default view. The layer.view.style of layers in the mapviews.layers list which are set to display:false will be set to display:none. The style layer group views with all containing layers hidden will also be set to display:none. Deactivating the hide_layers method will reset the style.display properties. The plugin is activated if the hide_layers flag is set in the workspace locale.

"hide_layers": true

measure_distance

The measure_distance plugin adds a button to the btn column in the default view. If activated, a custom interaction allows to draw a line segment, and shows the length of the geometry as a tooltip. The tooltip and units can be configured with the measure_distance key in the locale. The hereRoute key can be set with a value to draw an associated route along the waypoints of the linestring geometry from the drawing interaction.

"measure_distance": {
 "tooltip": "length",
 "units": "metric",
 "hereRoute": "pedestrian" // or "car"
}

reset_view

The reset_view plugin adds a button to the btn column in the default view. Button click will prompt for a reset of the view. Confirmation will strip all hooks from the URL and reload the browser location.