Maps¶
The Map component is used to represent geographical information.
Usage¶
A map provides location aware context and helps users to understand the spatial relationship between a specific point, like a site or building and other landmarks,
Interactive maps allow users to select, pan and zoom to obtain further information.
When to use¶
- Use it when users need to manage a large amount of locations that are geographically dispersed.
- Use it to provide an overview about the current status of all the locations.
- Use it to help users better understand the surrounding environment of a specific location like a site or building.
- Maps are particularly useful for users that need to physically visit a location, such as facility managers.
Best Practices for Maps¶
- Maps require a large amount of screen space to be readable. If space is limited, provide options to collapse/expand or hide it.
- If a specific location is not the main focus of the information being displayed, using a map for representation might not be required, since it doesn't provide any additional benefit to the user. Using a textual representation to display a location's address is more efficient.
- Try to limit the number of map actions, like zoom and find my location to 5.
Design¶
Elements¶
- Map, 2. Zoom actions, 3. Additional actions (optional), 4. Map pin, 5. Grouped locations
Location representation¶
A Map pin is used to represent a single location. If needed, Map pins can also be used to represent different status. Avoid mixing the Status color palette with the default color.
Locations are clustered together and represented by a donut chart when geographically close, allowing an efficient visualization of the locations and their status. When zoomed in, they are displayed as individual Map pins to provide a more accurate view.
The number represents the amount of locations that are grouped in that chart. The size of each slice indicates the relative quantity of locations in a specific state.
Code¶
The Element-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 on the official website API docs and further useful examples on their Examples Page. The source code is located in the OpenLayers GitHub repository.
For the cluster functionality and other additional features, the ol-ext extension is used. More info 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¶
Required Packages
npm install --save @siemens/maps-ng
# Also install the needed peer dependencies
npm install --save ol ol-ext ol-mapbox-style
Add library assets and CommonJs dependencies in your angular.json under the build options
{
"architect": {
"build": {
"options": {
"assets": [
// ... other assets
{
"glob": "**/*",
"input": "./node_modules/@siemens/maps-ng/assets",
"output": "/assets/"
}
],
// ... other options
"allowedCommonJsDependencies": [
"xml-utils/find-tags-by-name.js",
"xml-utils/get-attribute.js",
"web-worker",
"pbf",
"earcut",
"rbush"
]
}
}
}
}
Import the OpenLayers styles into your main global stylesheet:
@use 'ol/ol.css';
Add the library to the list of imports in your Angular AppModule like this:
// [...]
// Import this library and required dependencies
import { SiMapsNgModule } from '@siemens/maps-ng';
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
// Import this library
SiMapsNgModule
],
bootstrap: [AppComponent]
})
export class AppModule { }
And lastly, define a MapTiler key:
<si-map maptilerKey="REPLACE_WITH_YOUR_MAPTILER_KEY"></si-map>
Features¶
Grouping¶
Points on the map can be grouped in a way that they share the color provided in groupColors
. Also while clustered, points are grouped in a donut chart.
If you want points to be grouped, specify the group
property on a point object. The value of group
is then 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 following code:
<si-map [points]="points" [groupColors]="{ 1: 'red', 2: 'green', 3: 'blue', 4: 'black'}"></si-map>
Accessibility of custom colors
The usage of Element color definitions is strongly recommended to fulfill accessibility standards. Involve your UX specialist when using custom colors to ensure accessibility, especially important are appropriate contrasts for different themes.
Note: To override 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¶
A user can change the look of the actual map by passing a custom MapBox style to the component as styleJson
input. In this case, the maptilerKey
parameter is not needed as the custom style overrides it.
<si-map [styleJson]="styleJson"></si-map>
More info in the official MapBox Docs.
Customize tooltip length¶
A user can customize the tooltip width via maxLabelLength
see snippet below:
<si-map
class="flex-fill"
[points]="points"
[displayTooltipOnHover]="true"
[maptilerKey]="maptilerKey"
>
<si-map-tooltip [maxLabelLength]="50" />
</si-map>
Map example¶
SiMapComponent API Documentation¶
si-map
Input Properties¶
Name | Type | Default | Description |
---|---|---|---|
alwaysShowLabels ¶ | boolean | false | Show the label permanently next to the point. Normally the label is shown on hover or click. By enabling this it will always be visible next to the marker. |
autoZoomClusterClick ¶ | boolean | true | When disabled, clusters will no longer automatically be zoomed to on click. |
autoZoomFeatureClick ¶ | boolean | false | When enabled, features will be automatically zoom to on click. |
cluster ¶ | boolean | false | Enable or disable clustering of points on the map. |
clusterClickZoom ¶ | number | DEFAULT_CLUSTER_CLICK_ZOOM | Max zoom level for clicking on a cluster on the map. Defaults to 15. |
clusterDistance ¶ | number | DEFAULT_CLUSTER_DISTANCE | Defines range in which points are clustered. In pixels. |
clusterPopoverComponent ¶ | Type <any > | Custom popover component for clustering | |
displayPopoverOnClick ¶ | boolean | true | Option to switch on/off the display of popover when clicked. Default set to true (on). |
displayPopoverOnHover ¶ | boolean | false | Option to switch on/off popover when hovered. Default is set to false (off) |
displayTooltipOnClusterHover ¶ | boolean | false | Option to switch on/off the display of tooltip while hovering over cluster. |
displayTooltipOnHover ¶ | boolean | false | Option to switch on/off the display of tooltip while hovering over single point. |
featureClickZoom ¶ | number | DEFAULT_FEATURE_CLICK_ZOOM | Max zoom level which is used when clicking on feature on the map. Defaults to 15. |
featureSelectZoom ¶ | number | DEFAULT_FEATURE_SELECT_ZOOM | Zoom level when calling the select() method on the component. Defaults to 10. |
fitClusterPadding ¶ | [ number , number , number , number ] | [20, 20, 20, 20] | Padding (in pixels) applied to the map view when zooming to a cluster, preventing points from being clipped at the edges. Specified as [top, right, bottom, left]. |
fitGeoJsonPadding ¶ | number [] | [20, 20, 20, 20] | For GeoJson, padding (in pixels) to be cleared to fit the GeoJson inside the view after a click on it. Values in the array are: [top, right, bottom, left]. |
fitPointPadding ¶ | number [] | [20, 20, 20, 20] | For Point geometry, padding (in pixels) to be cleared to fit the point inside the view after a click on it. Values in the array are: [top, right, bottom, left]. |
geoJson ¶ | any | Payload of a geo-JSON object. | |
geoJsonProjection ¶ | string | 'EPSG:3857' | Projection format used to render the geo-JSON payload. |
globalZoom ¶ | number | DEFAULT_GLOBAL_ZOOM | Max zoom level on load or when clicking the reset button. Defaults to 5. |
groupColors ¶ | (Record <number , string > | ColorPalette ) | 'status' | Defines which colors should be used when points are grouped. Grouping means that points are painted with their group color and they are displayed as series in donut chart inside cluster. |
maptilerKey ¶ | string | Provide your key for MapTiler, this will use the default siemens element styles which can be used in both light and dark mode. Shouldn't be used together with styleJson. | |
markerAnimation ¶ | boolean | false | Enable or disable animation of markers. |
maxLabelLineLength ¶ | number | 20 | Maximum number of characters per line for always displayed labels of a point. If the label exceeds this limit, it will be wrapped or trimmed. If set to 0, label trimming will be disabled. This setting is effective only when alwaysShowLabels is enabled. Important: Changing this is not recommended in most cases and may cause issues with positioning of the labels. |
maxLabelLines ¶ | number | 3 | Maximum number of lines for always displayed labels of a point. If the label exceeds this limit, it will be trimmed. This setting is effective only when alwaysShowLabels is enabled and maxLabelLineLength is not 0. Important: Changing this is not recommended in most cases and may cause issues with positioning of the labels. |
multiWorld ¶ | boolean | true | Show multiple worlds, including points that cross the 180th meridian. |
nativeProperties ¶ | OverlayNativeProperties | - overlay: Layer for popup element, an element to be displayed over the map and attached to a single map location. - controls: List of controls to activate for map, additional controls like full screen, etc. can be added here. | |
points ¶ | MapPoint [] | Points to be rendered on the map as features. | |
popoverCloseOnClick ¶ | boolean | true | Close the popover on click |
popoverComponent ¶ | Type <any > | Custom popover component | |
popoverComponentProps ¶ | any | Custom popover component | |
styleFunction ¶ | StyleLike | Callback function to add custom styling to the drawn geo-JSON features. | |
styleJson ¶ | any | Type of background map, for example 'https://api.maptiler.com/maps/voyager/style.json?key=xxx' (Token key is required). The styleJson defines the tiler source and the used styles for different layers, should only be used if the siemens default styles by using maptilerKey isn't good enough. | |
moreText | TranslatableString | $localize`:@@SI_MAPS.TOOLTIP_MORE_TEXT:and {{length}} more...` | Cutoff text for tooltips, when cluster combines more than 4 features Deprecated: Use SiMapTooltipComponent instead to set the moreText input e.g. <si-map ...><si-map-tooltip [moreText]="'KEY_MORE'" /></si-map> . |
Output Properties¶
Name | Type | Description |
---|---|---|
pointsChange ¶ | MapPoint [] | Points to be rendered on the map as features. |
pointsRefreshed ¶ | void | Emitted when the points are available as features. So consumers can call methods like zoomToPoints() on the actual point list. |
pointsSelected ¶ | MapPoint [] | Emitted when points on the map are selected or de-selected |
Methods¶
Name | Type | Description |
---|---|---|
clear | clear() => void | Remove all points from map. |
refresh | refresh(points: MapPoint[]) => void | Updates the map with new set of points provided in argument. |
select | select(point: MapPoint) => void | Zoom in the provided point and display popover with additional information. |
MapTiler API key¶
Element Maps currently supports MapTiler as OSM tile source. To be able to use this service, an API key is required. This API key is unique per project and its use is limited to certain URLs (HTTP Origin Header allow-list).
As for most map services, the commercial use of the API is a paid service and requires account with active subscription. The procurement of such an account is not something Element offers for all of Siemens.
Testing¶
When running automated tests of your application, you should make sure to not load the map tiles. This drastically reduces the amount of map requests to maptiler that are limited in our contract. And for testing you want to test your map functionality and not the map data.
- Unit tests: Do simply not provide an API key during
- Playwright tests: Stub the
tiles.json
request (and some others) using page.route(...).
Types Documentation¶
Variable |
---|
Variable |
---|
Variable |
---|
Variable |
---|
Variable |
---|
|
| ||||||||
|
import imported from ol |
---|
Represents a translatable string. This can either be a translation key, e.g. ACTIONS.EDIT that will be automatically translated when displayed on the UI or a pre-translated string, e.g. Edit . Equivalent to a normal string in usage and functionality. |
---|
| ||||||
|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
|
Function |
---|
import imported from ol |
---|
import imported from ol |
---|
Class for grouping functionality | ||||||
---|---|---|---|---|---|---|
| ||||||
| ||||||
| ||||||
|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
import imported from ol |
---|
|
| ||||||||||||||||
| ||||||||||||||||
| ||||||||||||||||
|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| |||||||||||||||||
| |||||||||||||||||
|
Wrapper around an actual translation framework which is meant to be used internally by Element. Applications must not use this service. Use injectSiTranslateService to get an instance of the translation service. | |||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
|
Except where otherwise noted, content on this site is licensed under MIT License.