Element Maps¶

Usage¶

Use Element Maps when an application needs a ready-to-use map component with Element-specific behavior instead of assembling map features individually.

When to use¶

• To display and group location points with a predefined Element presentation.
• When built-in clustering, labels, tooltips, or popovers are required.
• When a high-level component is preferable to direct interaction with a map library.

Code¶

The si-map component uses the OpenLayers library. OpenLayers is a high-performance, feature-rich library for creating interactive geographical maps. It can display map tiles, vector data, and markers loaded from a wide range of sources.

The API documentation can be found in the official OpenLayers API docs, with further useful examples on the OpenLayers examples page. The source code is available in the OpenLayers GitHub repository.

For cluster functionality and other additional features, ol-ext is used. More information and documentation can be found in the ol-ext GitHub repository.

The OpenLayers ol-mapbox-style library is used to create OpenLayers maps from Mapbox Style Specification objects.

Usage¶

npm install --save @siemens/maps-ng @siemens/map-styles

# Also install the needed peer dependencies
npm install --save ol ol-ext ol-mapbox-style

Add library assets and CommonJS dependencies in angular.json under the build options:

{
  "architect": {
    "build": {
      "options": {
        "assets": [
          {
            "glob": "**/*",
            "input": "./node_modules/@siemens/maps-ng/assets",
            "output": "/assets/"
          }
        ],
        "allowedCommonJsDependencies": [
          "xml-utils/find-tags-by-name.js",
          "xml-utils/get-attribute.js",
          "web-worker",
          "pbf",
          "earcut",
          "rbush"
        ]
      }
    }
  }
}

Import the OpenLayers styles into the main global stylesheet:

@use 'ol/ol.css';

Import SiMapComponent into the component that displays the map:

import { Component } from '@angular/core';
import { SiMapComponent } from '@siemens/maps-ng';

@Component({
  selector: 'app-map',
  imports: [SiMapComponent],
  template: '<si-map maptilerKey="REPLACE_WITH_YOUR_MAPTILER_KEY" />'
})
export class MapComponent {}

Provide a MapTiler key when using the default map style:

<si-map maptilerKey="REPLACE_WITH_YOUR_MAPTILER_KEY"></si-map>

Features¶

Grouping¶

Points on the map can be grouped so they share the color provided in groupColors. While clustered, points are grouped in a donut chart.

To group points, specify the group property on a point object. The value of group is used to match the color from the default palette or groupColors, if provided. While groupColors is optional, the default color palette is status.

A custom color palette can be defined with the following code:

<si-map [points]="points" [groupColors]="{ 1: 'red', 2: 'green', 3: 'blue', 4: 'black'}"></si-map>

To override a group color, specify a marker color on the point object itself:

const point: MapPoint = {
  name: 'Point 1',
  lon: 11,
  lat: 10,
  group: 1,
  marker: {
    color: 'orange'
  }
};

Examples¶

Grouping with default status palette:

<si-map [points]="points"></si-map>

const points: MapPoint[] = [
  {
    name: 'Point 1',
    lon: 11,
    lat: 10,
    group: 1 // $element-status-information
  },
  {
    name: 'Point 2',
    lon: 11,
    lat: 10,
    group: 2 // $element-status-success
  },
  {
    name: 'Point 3',
    lon: 11,
    lat: 10,
    group: 3 // $element-status-warning
  },
  {
    name: 'Point 4',
    lon: 11,
    lat: 10,
    group: 4 // $element-status-danger
  }
];

Grouping with Element palette colors:

<si-map [points]="points" groupColors="element"></si-map>

const points: MapPoint[] = [
  {
    name: 'Point 1',
    lon: 11,
    lat: 10,
    group: 1 // $element-red-500 / 300 (depending on theme)
  },
  {
    name: 'Point 2',
    lon: 11,
    lat: 10,
    group: 2 // $element-orange-500
  },
  {
    name: 'Point 3',
    lon: 11,
    lat: 10,
    group: 3 // $element-blue-500
  },
  {
    name: 'Point 4',
    lon: 11,
    lat: 10,
    group: 4 // $element-yellow-500
  }
];

Custom Mapbox style¶

The map appearance can be changed by passing a custom Mapbox style to the component as the styleJson input. In this case, maptilerKey is not needed as the custom style overrides it.

<si-map [styleJson]="styleJson"></si-map>

See the official Mapbox documentation for more information.

Customize tooltip length¶

Customize the tooltip width with maxLabelLength:

<si-map
  class="flex-fill"
  [points]="points"
  [displayTooltipOnHover]="true"
  [maptilerKey]="maptilerKey"
>
  <si-map-tooltip [maxLabelLength]="50" />
</si-map>

Map example¶

SiMapComponent API Documentation¶

Input Properties¶

Output Properties¶

Methods¶

MapTiler API key¶

Element Maps currently supports MapTiler as an OSM tile source. An API key is required to use this service. The API key is unique per project and its use is limited to certain URLs through an HTTP Origin Header allow-list.

As with most map services, commercial use of the API is a paid service and requires an account with an active subscription. Element does not provide such an account for all of Siemens.

Testing¶

When running automated tests, do not load map tiles. This drastically reduces the number of MapTiler requests, which are limited by contract. Tests should cover the application's map functionality rather than the map data.

• Unit tests: Do not provide an API key.
• Playwright tests: Stub the tiles.json request and related requests using page.route(...).

Security considerations¶

The description of a map point can contain HTML and is rendered in the popover. Angular sanitizes this value. Do not pass untrusted content that was marked as trusted (e.g. via bypassSecurityTrustHtml). The point name is rendered as plain text.

Types Documentation¶