Core

Scope

The client's core is the base package to create clients in the POLAR environment.

It offers this functionality:

• Plugin mechanism
• @masterportal/masterportalapi functionality
• Localization mechanism

Interaction

If a client is rendered as part of another page, the zoom and drag-pan behaviour is different to if the client is rendered as complete page.
If it's part of another page, drag-panning on mobile devices is only usable if at least two fingers are being used while on desktop clients the user can only zoom if using the respective platform modifier key (e.g. CTRL).

It is important to note that the behaviour will be desktop-like on larger touchscreen devices (e.g. tablets).

Initialization / Configuration

It depends on the client how exactly the initialization will take place for the embedding programmer. However, the core mechanism remains the same.

The exported default object is an extended masterportalapi, adding the addPlugins and extending the createMap functions. For masterportalapi details, see their repository.

addPlugins

Before instantiating the map, all required plugins have to be added. Depending on how you use POLAR, this may already have been done. Ready-made clients (that is, packages prefixed @polar/client-) come with plugins prepared. You may add further plugins or proceed with createMap.

In case you're integrating new plugins, call addPlugins with an array of instances.

client.addPlugins([Plugin({ pluginConfig })])

In case you're writing a new plugin, it must fulfill the following API:

const Plugin = (options: PluginOptions) => (instance: Vue) =>
  instance.$store.dispatch('addComponent', {
    name: 'plugin', // unique technical name
    plugin: Plugin, // a vue component
    language, // an i18n locale batch
    options, // configuration; overriddable with mapConfiguration on createMap
    storeModule, // vuex store module, if required
  })

If the storeModule features a setupModule action, it will be executed automatically after initialization.

initializeLayerList

Layers intended to be used in the map have to be initialized by calling initializeLayerList with a service register.
This register may either be a link to a predefined service register like the Hamburg service register, or the custom service register that is also used in mapConfiguration.layerConf.

core.rawLayerList.initializeLayerList(services: mapConfiguration.layerConf | string, callback?: Function)

createMap is usually called inside the callback or directly after this function call.

createMap

The map is created by calling the createMap method. Depending on how you use POLAR, this may already have been done, as some clients come as ready-made standalone HTML pages that do this for you.

MapClient.createMap({
  // arbitrary id, must point to a div
  containerId: 'polarstern',
  // see below
  mapConfiguration,
}).then((map) => {
  /* Your Code, e.g. for setting up callbacks. */
})

mapConfiguration

The mapConfiguration allows controlling many client instance details.

import locales from './locales'

const mapConfiguration = {
  stylePath: '../dist/polar-client.css',
  checkServiceAvailability: true,
  language: 'de',
  locales, // the languageOptions object will normally be outsourced to another file
  layerConf, // the layerConf object will normally be outsourced to another file - for more information, see the relevant chapter
  layers: [
    // parts of the layer configuration can be outsourced to another file
    // and referenced in the mapConfiguration by id like the second layer
    {
      id: 'backgroundmap',
      name: 'WMS DE BASEMAP.DE WEB RASTER',
      url: 'https://sgx.geodatenzentrum.de/wms_basemapde',
      typ: 'WMS',
      layers: 'de_basemapde_web_raster_grau',
      format: 'image/png',
      version: '1.3.0',
      singleTile: false,
      transparent: true,
    },
    {
      id: '1561',
      visibility: true,
      type: 'mask',
      name: 'Building Plans',
      minZoom: 2,
    },
  ],
  addressSearch: {
    displayComponent: false,
  },
  export: {
    showPdf: false,
  },
  ...
}

mapConfiguration.LanguageOption

A language option is an object consisting of a type (its language key) and the i18next resource definition. You may e.g. decide that the texts offered in the LayerChooser do not fit the style of your client, or that they could be more precise in your situation since you're only using very specific overlays.

An example for a LanguageOption array usable in createMap is this array:

const languageOptions: LanguageOption[] = [
  {
    type: 'de',
    resources: {
      plugins: {
        layerChooser: {
          maskTitle: 'Bahnstrecken',
        },
      },
    },
  },
  {
    type: 'en',
    resources: {
      plugins: {
        layerChooser: {
          maskTitle: 'Railway lines',
        },
      },
    },
  },
]

To figure out the name of the locales to override, inspect the matching plugin in GitHub's file browser. In packages/plugins, open the plugin you desire to override. Each plugin's src folder contains a language.ts listing all used locale keys with appropriate nesting.

mapConfiguration.extendedMasterportalapiMarkers

Example configuration:

extendedMasterportalapiMarkers: {
  layers: ['reportServiceLayerId'],
  defaultStyle: {
    stroke: '#FFFFFF',
    fill: '#005CA9',
  },
  hoverStyle: {
    stroke: '#46688E',
    fill: '#8BA1B8',
  },
  selectionStyle: {
    stroke: '#FFFFFF',
    fill: '#E10019',
  },
  unselectableStyle: {
    stroke: '#FFFFFF',
    fill: '#333333'
  },
  isSelectable: (feature: Feature) => feature.get('indicator')
  clusterClickZoom: true,
  dispatchOnMapSelect: ['plugin/iconMenu/openMenuById', 'gfi'],
},

mapConfiguration.extendedMasterportalapiMarkers.MarkerStyle

Example configuration:

defaultStyle: {
  stroke: '#FFFFFF',
  fill: '#005CA9',
},

A full documentation of the masterportalapiPolygonFillHatch is available at the Masterportal's documentation file style.json.md, chapter 'Polygon.polygonFillHatch'. The basic usage is quoted below for quick lookup. For more details, visual examples, and expert features, see there.

Name	Required	Type	Default	Description
backgroundColor	no	Number[]	[0, 0, 0, 1]	Background color of polygon.
lineWidth	no	Number	10	Line width of drawn pattern. To achieve an even distribution in diagonal and zig-line pattern, choose lineWidth as (1/3 * size). For triangle and diamond, a lineWidth of 1 must be chosen. For rectangle, a lineWidth of at most (1/4 * size) should be chosen. Deviating from these rules is not harmful, but patterns may seem off.
pattern	no	enum["diagonal", "diagonal-right", "zig-line", "zig-line-horizontal", "circle", "rectangle", "triangle", "diamond"]/Object	"diagonal"	Draw pattern. You may either use a pre-defined pattern from the enum or specify one yourself.
patternColor	no	Number[]	[255, 255, 255, 1]	Fill color of pattern drawn on polygon.
size	no	Number	30	Edge length of a singular repeated pattern element.

mapConfiguration.featureStyles

Vector Layers (GeoJSON and WFS) can also be styled on the client side. Configuration and implementation is based on style.json of @masterportal/masterportalapi. For the full documentation, including all rules that are applied when parsing the configuration, see the above linked documentation.

Example styling some points of a layer gray that have the value food in the property not bamboo. All Other features will use the provided default green styling. A Layer needs to use the property styleId in its mapConfiguration.layers entry and set it to panda to use this styling.

[
  {
    "styleId": "panda",
    "rules": [
      {
        "conditions": {
          "properties": {
            "food": "bamboo"
          }
        },
        "style": {
          "circleStrokeColor": [3, 255, 1, 1],
          "circleFillColor": [3, 255, 1, 1]
        }
      },
      { 
        "style": {
          "circleStrokeColor": [128, 128, 128, 1],
          "circleFillColor": [128, 128, 128, 1]
        }
      }
    ]
  }
]

<...masterportalapi.fields>

The <...masterportalapi.fields> means that any masterportalapi field may also be used here directly in the mapConfiguration. The fields described here are fields that are interesting for the usage of POLAR. Fields that are not set as required have default values.

{
  startResolution: 264.583190458,
  startCenter: [553655.72, 6004479.25],
  extent: [426205.6233, 5913461.9593, 650128.6567, 6101486.8776],
  epsg: 'EPSG:25832',
  options: [
    { resolution: 66.14579761460263, scale: 250000, zoomLevel: 0 },
    { resolution: 26.458319045841044, scale: 100000, zoomLevel: 1 },
    { resolution: 15.874991427504629, scale: 60000, zoomLevel: 2 },
    { resolution: 10.583327618336419, scale: 40000, zoomLevel: 3 },
    { resolution: 5.2916638091682096, scale: 20000, zoomLevel: 4 },
    { resolution: 2.6458319045841048, scale: 10000, zoomLevel: 5 },
    { resolution: 1.3229159522920524, scale: 5000, zoomLevel: 6 },
    { resolution: 0.6614579761460262, scale: 2500, zoomLevel: 7 },
    { resolution: 0.2645831904584105, scale: 1000, zoomLevel: 8 },
    { resolution: 0.1322915952292052, scale: 500, zoomLevel: 9 },
  ],
  namedProjections: [
    [
      'EPSG:25832',
      '+proj=utm +zone=32 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs',
    ],
  ],
}

mapConfiguration.layerConf

The layer configuration (or: service register) is read by the @masterportal/masterportalapi. The full definition can be read here.

However, not all listed services have been implemented in the @masterportal/masterportalapi yet, and no documentation regarding implemented properties exists there yet.

Whitelisted and confirmed parameters include:

• WMS: id, name, url, typ, format, version, transparent, layers, STYLES
• WFS: id, name, url, typ, outputFormat, version, featureType
• WMTS: id, name, urls, typ, capabilitiesUrl, optionsFromCapabilities, tileMatrixSet, layers, legendURL, format, coordinateSystem, origin, transparent, tileSize, minScale, maxScale, requestEncoding, resLength
• GeoJSON: id, name, url, typ, version, minScale, maxScale, legendURL

Example services register

[
  {
    "id": "my-wfs-id",
    "name": "Service name",
    "url": "Service url",
    "typ": "WFS",
    "outputFormat": "XML",
    "version": "1.1.0",
    "featureType": "ns:featureType"
  },
  {
    "id": "my-wms-id",
    "name": "Service name",
    "url": "Service url",
    "typ": "WMS",
    "format": "image/png",
    "version": "1.3.0",
    "transparent": true,
    "layers": ["A", "B"]
  },
  {
    "id": "my-self-defined-wmts",
    "urls": [
      "url1/{TileMatrix}/{TileCol}/{TileRow}.png",
      "url2/{TileMatrix}/{TileCol}/{TileRow}.png",
      "url3/{TileMatrix}/{TileCol}/{TileRow}.png"
    ],
    "typ": "WMTS",
    "format": "image/png",
    "coordinateSystem": "EPSG:3857",
    "origin": [-20037508.3428, 20037508.3428],
    "transparent": false,
    "tileSize": "256",
    "minScale": "1",
    "maxScale": "2500000",
    "tileMatrixSet": "google3857",
    "requestEncoding": "REST",
    "resLength": "20"
  },
  {
    "id": "my-capabilities-wmts",
    "capabilitiesUrl": "WMTS capabilities url",
    "urls": "WMTS url",
    "optionsFromCapabilities": true,
    "tileMatrixSet": "EU_EPSG_25832_TOPPLUS",
    "typ": "WMTS",
    "layers": "layer-name",
    "legendURL": "my-legend-url"
  },
  {
    "id": "my-geojson",
    "name": "My GeoJSON data",
    "url": "Service url",
    "typ": "GeoJSON",
    "version": "1.0",
    "minScale": "0",
    "maxScale": "2500000",
    "legendURL": ""
  }
]

Since this is the base for many functions, the service id set in this is used to reference map material in many places of the map client.

zoomOption

layer

layers: [
  {
    id: 'basemap',
    name: 'Basemap Grayscale',
  },
  {
    id: 'my-wfs',
    name: 'My WFS service',
  },
]

<plugin.fields>

Plugins in POLAR are modular components that extend the functionality of the map client. They can be added using the addPlugins method and configured through the mapConfiguration object. Each plugin has its own set of fields and options that can be customized.

On how to configure a plugin, see the respective plugin. The configuration is given in the mapConfiguration object by the plugin's name as specified in its respective documentation.

Global Plugin Parameters

Most plugins honor this additional field.

Example Configuration

For example, a @polar/plugin-address-search plugin can be configured like this:

{
  addressSearch: {
    // Plugin-specific configuration
    displayComponent: true, // Optional field to control UI elements
    // ...
  }
}

mapConfiguration.vuetify

These fields let you e.g. specify a Vuetify-Theme. For more options, refer to the official vuetify documentation.

Additionally to the regular fields, primaryContrast and secondaryContrast are interpreted. They serve as contrast colors to their respective fields and are used for e.g. button icons.

{
  theme: {
    themes: {
      light: {
        primary: "black",
        primaryContrast: "white",
        secondary: "#c0ffee",
        secondaryContrast: "#de1e7e"
      }
    }
  }
}

Store

The core module features a vuex root store that all plugin vuex modules are plugged into. However, the root contents are only relevant to plugins. It is accessible with map.$store, and can be used as a starting point for plugin access.

To ease use, the map instance also features a subscribe method that will register a watcher to any state field. Please mind that only documented paths should be used, and all others are subject to change without notice.

// state subscription – listening to data held by the map client
map.subscribe('some/key', (value) => {
  // do something with the value
})

// getter subscription – these are computed values from various sources
map.$store.watch(
    (_, getters) => getters['some/key'],
    (value) => {
        // effect
    }
)

This is, for example, useful to listen to search results, draw features, or marker coordinates. The plugins document how exactly to use their respective fields.

To add content to the MoveHandle, the mutation setMoveHandle can be used. The values needed are described in @polar/lib-custom-types:MoveHandleProperties.