From 90f0dcf497378cb1166c2b96bc71b007a245b4c5 Mon Sep 17 00:00:00 2001 From: Ekhorn Date: Mon, 24 Nov 2025 14:59:56 +0100 Subject: [PATCH 1/5] Manager configuration docs to manager UI documentation --- .../deploying/configuring-the-manager-ui.md | 493 ------------------ docs/user-guide/manager-ui/appearance.md | 493 ++++++++++++++++++ 2 files changed, 493 insertions(+), 493 deletions(-) delete mode 100644 docs/user-guide/deploying/configuring-the-manager-ui.md diff --git a/docs/user-guide/deploying/configuring-the-manager-ui.md b/docs/user-guide/deploying/configuring-the-manager-ui.md deleted file mode 100644 index 95c7271f..00000000 --- a/docs/user-guide/deploying/configuring-the-manager-ui.md +++ /dev/null @@ -1,493 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Configuring the Manager UI - -The settings option 'Appearance' can be used in a [custom deployment](custom-deployment.md). You can use it to style your deployment and configure how the pages of the Manager display the assets and attributes in your system. Some of these settings can be changed visually in the user interface, others can be set when selecting the JSON editor. The configuration gets stored in the manager_config file. - -In this user guide we will use an example JSON manager_config and give a short description of each section you could include. Note that some pages have a default config that you can overwrite using the manager_config. - -:::note - -By default Superusers (e.g. the 'admin' user of the master realm) will see these styling changes. However, if ```"manager":{"applyConfigToAdmin":false}``` is set in the manager_config, most styling changes will _not_ show. This option can be set so that the 'admin' user is not limited by what is set in the config. - -::: - -
-View the example manager_config used in the sections on this page. - -```json -{ - "pages": { - "map": { - "card": { - "default": { - "exclude": [ - "notes" - ] - }, - "assetTypes": { - "WeatherAsset": { - "exclude": [ - "location", - "notes", - "model", - "manufacturer" - ] - } - } - } - }, - "rules": { - "rules": { - "controls": { - "allowedLanguages": ["JSON", "FLOW", "GROOVY"], - "allowedActionTargetTypes": { - "actions": { - "email": [ - "CUSTOM", "USER" - ], - "push": [ - "ASSET", "USER" - ] - } - } - }, - "descriptors": { - "all": { - "excludeAssets": [ - "TradfriLightAsset", - "TradfriPlugAsset", - "ArtnetLightAsset" - ], - "assets": { - "*": { - "excludeAttributes": [ - "location" - ] - } - } - } - } - } - }, - "assets": { - "tree": { - "add": { - "typesParent": { - "default": { - "exclude": [ - "TradfriLightAsset", - "TradfriPlugAsset", - "ArtnetLightAsset", - "ArtnetAgent", - "MacroAgent", - "ControllerAgent", - "KNXAgent", - "ZWAgent", - "TradfriAgent", - "TimerAgent", - "VelbusTcpAgent", - "VelbusSerialAgent" - ] - } - } - } - }, - "viewer": { - "assetTypes": { - "WeatherAsset": { - "viewerStyles": {}, - "panels": [ - { - "type": "group", - "title": "underlyingAssets" - }, - { - "type": "info", - "title": "location", - "properties": { - "include": [] - }, - "attributes": { - "include": [ - "location" - ], - "itemConfig": { - "location": { - "label": "" - } - } - } - }, - { - "type": "info", - "hideOnMobile": true, - "properties": { - "include": [] - }, - "attributes": { - "include": [ - "notes", - "manufacturer", - "model" - ] - } - }, - { - "type": "info", - "title": "Weather data", - "attributes": { - "exclude": [ - "location", - "radiation", - "rainfall", - "uVIndex", - "currentWeather", - "notes", - "manufacturer", - "model" - ] - }, - "properties": { - "include": [] - } - }, - { - "type": "info", - "title": "Extra details", - "column": 1, - "properties": { - "include": [] - }, - "attributes": { - "include": [ - "rainfall", - "uVIndex" - ] - } - }, - { - "type": "history", - "column": 1 - }, - { - "type": "linkedUsers", - "column": 1 - } - ] - } - }, - "historyConfig": { - "table": { - "attributeNames": { - "optimiseTarget": { - "columns": [ - { - "header": "Optimise target", - "type": "prop", - "path": "$." - }, - { - "header": "Timestamp", - "type": "timestamp" - } - ] - } - } - } - } - } - } - }, - "realms": { - "default": { - "appTitle": "ACME IoT", - "headers": [ - "map", "assets", "rules", "insights", "language", "users", "roles", "account", "logs", "logout" - ], - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #1b5630; --or-app-color5: #CCCCCC;}", - "logo": "/images/logo.png", - "logoMobile": "/images/logo-mobile.png", - "favicon": "/images/favicon.png", - "language": "en" - } - } -} -``` - -
- -**Map - Card:** -You can set the attributes to exclude (or include) on the top right card of the map when an asset is selected. This can be done for all asset types (by using default), or per asset type (as shown for WeatherAsset). -```json -{ - "pages": { - "map": { - "card": { - "default": { - "exclude": [ - "notes" - ] - }, - "assetTypes": { - "WeatherAsset": { - "exclude": [ - "location", - "notes", - "model", - "manufacturer" - ] - } - } - } - }, -``` -**Map - Marker config:** -This configures how the markers behave. They can either change their colour based on an attribute value (number, boolean, or string), show a label with or without units, and/or show the direction an asset is facing. Note that this part of the config is not in the manager_config used in the manager demo yet. -```json -"markers": { - "ElectricityProducerSolarAsset": { - "attributeName": "energyExportTotal", - "showLabel": true, - "showUnits": true, - "colours": { - "type": "range", - "ranges": [ - { - "min": 0, - "colour": "39B54A" - }, - { - "min": 50, - "colour": "F7931E" - }, - { - "min": 80, - "colour": "C1272D" - } - ] - } - }, - "LightAsset": { - "attributeName": "onOff", - "showLabel": false, - "showUnits": false, - "colours": { - "type": "boolean", - "true": "6ae8fc", - "false": "016170" - } - } - -``` -**Rules - Controls:** -Set which types of rules are available (for users with the correct permissions), and which actions a rule can perform. -```json - "rules": { - "rules": { - "controls": { - "allowedLanguages": ["JSON", "FLOW", "GROOVY"], - "allowedActionTargetTypes": { - "actions": { - "email": [ - "CUSTOM", "USER" - ], - "push": [ - "ASSET", "USER" - ] - } - } - }, -``` -**Rules - When-Then:** -Set which assettypes are excluded from the list of asset types that can be selected in the When-Then rule. Additionally you can set per asset (or all '*') which attributes should be excluded from the select list. -```json - "descriptors": { - "all": { - "excludeAssets": [ - "TradfriLightAsset", - "TradfriPlugAsset", - "ArtnetLightAsset" - ], - "assets": { - "*": { - "excludeAttributes": [ - "location" - ] - } - } - } - } - } - }, -``` -**Assets - tree:** Exclude asset types from the 'Add asset' dialog. -```json - "assets": { - "tree": { - "add": { - "typesParent": { - "default": { - "exclude": [ - "TradfriLightAsset", - "TradfriPlugAsset", - "ArtnetLightAsset", - "ArtnetAgent", - "MacroAgent", - "ControllerAgent", - "KNXAgent", - "ZWAgent", - "TradfriAgent", - "TimerAgent", - "VelbusTcpAgent", - "VelbusSerialAgent" - ] - } - } - } - }, -``` -**Assets - viewer:** Configure which panels are shown on the assets page. You can include or exclude attributes to show per panel. These panels can be set for all asset types, or specified per type. This is an overwrite of the default config of the [asset-viewer](https://github.com/openremote/openremote/blob/master/ui/component/or-asset-viewer/src/index.ts). In `historyConfig` an example is given on how to specify the columns shown in a table for an attribute that is not a number or boolean; if no config is given, it will automatically create columns. -```json - "viewer": { - "assetTypes": { - "WeatherAsset": { - "viewerStyles": {}, - "panels": [ - { - "type": "group", - "title": "underlyingAssets" - }, - { - "type": "info", - "title": "location", - "properties": { - "include": [] - }, - "attributes": { - "include": [ - "location" - ], - "itemConfig": { - "location": { - "label": "" - } - } - } - }, - { - "type": "info", - "hideOnMobile": true, - "properties": { - "include": [] - }, - "attributes": { - "include": [ - "notes", - "manufacturer", - "model" - ] - } - }, - { - "type": "info", - "title": "Weather data", - "attributes": { - "exclude": [ - "location", - "radiation", - "rainfall", - "uVIndex", - "currentWeather", - "notes", - "manufacturer", - "model" - ] - }, - "properties": { - "include": [] - } - }, - { - "type": "info", - "title": "Extra details", - "column": 1, - "properties": { - "include": [] - }, - "attributes": { - "include": [ - "rainfall", - "uVIndex" - ] - } - }, - { - "type": "history", - "column": 1 - }, - { - "type": "linkedUsers", - "column": 1 - } - ] - } - }, - "historyConfig": { - "table": { - "attributeNames": { - "optimiseTarget": { - "columns": [ - { - "header": "Optimise target", - "type": "prop", - "path": "$." - }, - { - "header": "Timestamp", - "type": "timestamp" - } - ] - } - } - } - } - } -``` -**Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logos are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. -```json - "realms": { - "default": { - "appTitle": "ACME IoT", - "headers": [ - "map", "assets", "rules", "insights", "language", "users", "roles", "account", "logs", "logout" - ], - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #1b5630; --or-app-color5: #CCCCCC;}", - "logo": "/images/logo.png", - "logoMobile": "/images/logo-mobile.png", - "favicon": "/images/favicon.png", - "language": "en" - }, - "master": { - "appTitle": "ACME Master", - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", - "logo": "/images/logo.png", - "logoMobile": "/images/logo-mobile.png", - "favicon": "/images/logo-favicon.png", - "language": "en" - }, - "clienta": { - "appTitle": "Client A", - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", - "logo": "/images/clienta-logo.png", - "logoMobile": "/images/clienta-logoMobile.png", - "favicon": "/images/clienta-favicon.png", - "language": "de" - } - } -} -``` -This is what the --or-app-colors look like in the demo deployment: -![Default colors in OpenRemote](img/or-app-colors.jpg) diff --git a/docs/user-guide/manager-ui/appearance.md b/docs/user-guide/manager-ui/appearance.md index d832bad2..e5d0a66d 100644 --- a/docs/user-guide/manager-ui/appearance.md +++ b/docs/user-guide/manager-ui/appearance.md @@ -32,3 +32,496 @@ The following tile servers have been tested. | [Carto](https://carto.com/) | Basemaps | | | [Mapbox](https://mapbox.com/) | Tested [Classic Mapbox styles](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles) using `https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=pk.ey...` | Import settings | | [OpenFreeMap](https://openfreemap.org/) | All maps can be imported | | +--- +sidebar_position: 2 +--- + +# Configuring the Manager UI + +The settings option 'Appearance' can be used in a [custom deployment](custom-deployment.md). You can use it to style your deployment and configure how the pages of the Manager display the assets and attributes in your system. Some of these settings can be changed visually in the user interface, others can be set when selecting the JSON editor. The configuration gets stored in the manager_config file. + +In this user guide we will use an example JSON manager_config and give a short description of each section you could include. Note that some pages have a default config that you can overwrite using the manager_config. + +:::note + +By default Superusers (e.g. the 'admin' user of the master realm) will see these styling changes. However, if ```"manager":{"applyConfigToAdmin":false}``` is set in the manager_config, most styling changes will _not_ show. This option can be set so that the 'admin' user is not limited by what is set in the config. + +::: + +
+View the example manager_config used in the sections on this page. + +```json +{ + "pages": { + "map": { + "card": { + "default": { + "exclude": [ + "notes" + ] + }, + "assetTypes": { + "WeatherAsset": { + "exclude": [ + "location", + "notes", + "model", + "manufacturer" + ] + } + } + } + }, + "rules": { + "rules": { + "controls": { + "allowedLanguages": ["JSON", "FLOW", "GROOVY"], + "allowedActionTargetTypes": { + "actions": { + "email": [ + "CUSTOM", "USER" + ], + "push": [ + "ASSET", "USER" + ] + } + } + }, + "descriptors": { + "all": { + "excludeAssets": [ + "TradfriLightAsset", + "TradfriPlugAsset", + "ArtnetLightAsset" + ], + "assets": { + "*": { + "excludeAttributes": [ + "location" + ] + } + } + } + } + } + }, + "assets": { + "tree": { + "add": { + "typesParent": { + "default": { + "exclude": [ + "TradfriLightAsset", + "TradfriPlugAsset", + "ArtnetLightAsset", + "ArtnetAgent", + "MacroAgent", + "ControllerAgent", + "KNXAgent", + "ZWAgent", + "TradfriAgent", + "TimerAgent", + "VelbusTcpAgent", + "VelbusSerialAgent" + ] + } + } + } + }, + "viewer": { + "assetTypes": { + "WeatherAsset": { + "viewerStyles": {}, + "panels": [ + { + "type": "group", + "title": "underlyingAssets" + }, + { + "type": "info", + "title": "location", + "properties": { + "include": [] + }, + "attributes": { + "include": [ + "location" + ], + "itemConfig": { + "location": { + "label": "" + } + } + } + }, + { + "type": "info", + "hideOnMobile": true, + "properties": { + "include": [] + }, + "attributes": { + "include": [ + "notes", + "manufacturer", + "model" + ] + } + }, + { + "type": "info", + "title": "Weather data", + "attributes": { + "exclude": [ + "location", + "radiation", + "rainfall", + "uVIndex", + "currentWeather", + "notes", + "manufacturer", + "model" + ] + }, + "properties": { + "include": [] + } + }, + { + "type": "info", + "title": "Extra details", + "column": 1, + "properties": { + "include": [] + }, + "attributes": { + "include": [ + "rainfall", + "uVIndex" + ] + } + }, + { + "type": "history", + "column": 1 + }, + { + "type": "linkedUsers", + "column": 1 + } + ] + } + }, + "historyConfig": { + "table": { + "attributeNames": { + "optimiseTarget": { + "columns": [ + { + "header": "Optimise target", + "type": "prop", + "path": "$." + }, + { + "header": "Timestamp", + "type": "timestamp" + } + ] + } + } + } + } + } + } + }, + "realms": { + "default": { + "appTitle": "ACME IoT", + "headers": [ + "map", "assets", "rules", "insights", "language", "users", "roles", "account", "logs", "logout" + ], + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #1b5630; --or-app-color5: #CCCCCC;}", + "logo": "/images/logo.png", + "logoMobile": "/images/logo-mobile.png", + "favicon": "/images/favicon.png", + "language": "en" + } + } +} +``` + +
+ +**Map - Card:** +You can set the attributes to exclude (or include) on the top right card of the map when an asset is selected. This can be done for all asset types (by using default), or per asset type (as shown for WeatherAsset). +```json +{ + "pages": { + "map": { + "card": { + "default": { + "exclude": [ + "notes" + ] + }, + "assetTypes": { + "WeatherAsset": { + "exclude": [ + "location", + "notes", + "model", + "manufacturer" + ] + } + } + } + }, +``` +**Map - Marker config:** +This configures how the markers behave. They can either change their colour based on an attribute value (number, boolean, or string), show a label with or without units, and/or show the direction an asset is facing. Note that this part of the config is not in the manager_config used in the manager demo yet. +```json +"markers": { + "ElectricityProducerSolarAsset": { + "attributeName": "energyExportTotal", + "showLabel": true, + "showUnits": true, + "colours": { + "type": "range", + "ranges": [ + { + "min": 0, + "colour": "39B54A" + }, + { + "min": 50, + "colour": "F7931E" + }, + { + "min": 80, + "colour": "C1272D" + } + ] + } + }, + "LightAsset": { + "attributeName": "onOff", + "showLabel": false, + "showUnits": false, + "colours": { + "type": "boolean", + "true": "6ae8fc", + "false": "016170" + } + } + +``` +**Rules - Controls:** +Set which types of rules are available (for users with the correct permissions), and which actions a rule can perform. +```json + "rules": { + "rules": { + "controls": { + "allowedLanguages": ["JSON", "FLOW", "GROOVY"], + "allowedActionTargetTypes": { + "actions": { + "email": [ + "CUSTOM", "USER" + ], + "push": [ + "ASSET", "USER" + ] + } + } + }, +``` +**Rules - When-Then:** +Set which assettypes are excluded from the list of asset types that can be selected in the When-Then rule. Additionally you can set per asset (or all '*') which attributes should be excluded from the select list. +```json + "descriptors": { + "all": { + "excludeAssets": [ + "TradfriLightAsset", + "TradfriPlugAsset", + "ArtnetLightAsset" + ], + "assets": { + "*": { + "excludeAttributes": [ + "location" + ] + } + } + } + } + } + }, +``` +**Assets - tree:** Exclude asset types from the 'Add asset' dialog. +```json + "assets": { + "tree": { + "add": { + "typesParent": { + "default": { + "exclude": [ + "TradfriLightAsset", + "TradfriPlugAsset", + "ArtnetLightAsset", + "ArtnetAgent", + "MacroAgent", + "ControllerAgent", + "KNXAgent", + "ZWAgent", + "TradfriAgent", + "TimerAgent", + "VelbusTcpAgent", + "VelbusSerialAgent" + ] + } + } + } + }, +``` +**Assets - viewer:** Configure which panels are shown on the assets page. You can include or exclude attributes to show per panel. These panels can be set for all asset types, or specified per type. This is an overwrite of the default config of the [asset-viewer](https://github.com/openremote/openremote/blob/master/ui/component/or-asset-viewer/src/index.ts). In `historyConfig` an example is given on how to specify the columns shown in a table for an attribute that is not a number or boolean; if no config is given, it will automatically create columns. +```json + "viewer": { + "assetTypes": { + "WeatherAsset": { + "viewerStyles": {}, + "panels": [ + { + "type": "group", + "title": "underlyingAssets" + }, + { + "type": "info", + "title": "location", + "properties": { + "include": [] + }, + "attributes": { + "include": [ + "location" + ], + "itemConfig": { + "location": { + "label": "" + } + } + } + }, + { + "type": "info", + "hideOnMobile": true, + "properties": { + "include": [] + }, + "attributes": { + "include": [ + "notes", + "manufacturer", + "model" + ] + } + }, + { + "type": "info", + "title": "Weather data", + "attributes": { + "exclude": [ + "location", + "radiation", + "rainfall", + "uVIndex", + "currentWeather", + "notes", + "manufacturer", + "model" + ] + }, + "properties": { + "include": [] + } + }, + { + "type": "info", + "title": "Extra details", + "column": 1, + "properties": { + "include": [] + }, + "attributes": { + "include": [ + "rainfall", + "uVIndex" + ] + } + }, + { + "type": "history", + "column": 1 + }, + { + "type": "linkedUsers", + "column": 1 + } + ] + } + }, + "historyConfig": { + "table": { + "attributeNames": { + "optimiseTarget": { + "columns": [ + { + "header": "Optimise target", + "type": "prop", + "path": "$." + }, + { + "header": "Timestamp", + "type": "timestamp" + } + ] + } + } + } + } + } +``` +**Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logos are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. +```json + "realms": { + "default": { + "appTitle": "ACME IoT", + "headers": [ + "map", "assets", "rules", "insights", "language", "users", "roles", "account", "logs", "logout" + ], + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #1b5630; --or-app-color5: #CCCCCC;}", + "logo": "/images/logo.png", + "logoMobile": "/images/logo-mobile.png", + "favicon": "/images/favicon.png", + "language": "en" + }, + "master": { + "appTitle": "ACME Master", + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", + "logo": "/images/logo.png", + "logoMobile": "/images/logo-mobile.png", + "favicon": "/images/logo-favicon.png", + "language": "en" + }, + "clienta": { + "appTitle": "Client A", + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", + "logo": "/images/clienta-logo.png", + "logoMobile": "/images/clienta-logoMobile.png", + "favicon": "/images/clienta-favicon.png", + "language": "de" + } + } +} +``` +This is what the --or-app-colors look like in the demo deployment: +![Default colors in OpenRemote](img/or-app-colors.jpg) From a1d11cdcb53ff83cd5b1f7f52c83d03effdddc51 Mon Sep 17 00:00:00 2001 From: Ekhorn Date: Wed, 26 Nov 2025 09:31:01 +0100 Subject: [PATCH 2/5] Update manager UI documentation --- .../deploying/configuring-the-manager-ui.md | 9 + docs/user-guide/manager-ui/appearance.md | 388 ++++++++++-------- .../img/or-app-colors.jpg | Bin 3 files changed, 226 insertions(+), 171 deletions(-) create mode 100644 docs/user-guide/deploying/configuring-the-manager-ui.md rename docs/user-guide/{deploying => manager-ui}/img/or-app-colors.jpg (100%) diff --git a/docs/user-guide/deploying/configuring-the-manager-ui.md b/docs/user-guide/deploying/configuring-the-manager-ui.md new file mode 100644 index 00000000..2dd41b66 --- /dev/null +++ b/docs/user-guide/deploying/configuring-the-manager-ui.md @@ -0,0 +1,9 @@ +--- +sidebar_position: 2 +--- + +# Configuring the Manager UI + +The settings option 'Appearance' can be used in a [custom deployment](custom-deployment.md). You can use it to style your deployment and configure how the pages of the Manager display the assets and attributes in your system. Some of these settings can be changed visually in the user interface, others can be set when selecting the JSON editor. The configuration gets stored in the manager_config file. + +See [Manager UI - Appearance](../manager-ui/appearance) on how to configure the manager appearance. diff --git a/docs/user-guide/manager-ui/appearance.md b/docs/user-guide/manager-ui/appearance.md index e5d0a66d..86a9ed51 100644 --- a/docs/user-guide/manager-ui/appearance.md +++ b/docs/user-guide/manager-ui/appearance.md @@ -4,41 +4,9 @@ sidebar_position: 3 # Appearance Page -## Map Settings - -If you want to adjust the map styling. You can change the map under Map Settings. Here you have the following options: - -| Method | Description | When to use? | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| Style JSON URL | Override the default map settings with a `style.json` URL (e.g. `https://api.example.com/maps/streets/style.json?key=your_key`) from a Map/Tile provider that supports MapLibre (see [providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)). | If you want to configure a different map quickly. | -| Import Style Settings | After configuring a Style JSON URL you can import it to include the layers allowing you to adjust the map styling. You may optionally configure a Tile server URL (to see more of a map). | If you want to be able to edit the map styling in OpenRemote, but also use an external map. | -| Realm Map Styling | You can add GeoJSON based points, lines and shapes from GeoJSON files. For creating GeoJSON files, you can use e.g. https://geojson.io/. For searching existing GeoJSON map layers, you can use https://overpass-turbo.eu/. | If you want to add map layers per realm. | -| Upload Custom `.mbtiles` | The uploaded map will be used instead of the default (see [working on maps](../../developer-guide/working-on-maps#uploading-mbtiles) for more). | If you happen to have an `.mbtiles` file and want to view a different part of the world. | -| Custom Deployment | Configure the map through [custom deployments](../deploying/custom-deployment.md#map-deploymentmap). | If you want full control over the configurations on the server (advanced usage). | - -:::note -OpenRemote picks how to render the map based on the configurations set in the following order: 1) `Style JSON URL` 2) `Import Style Settings` & `Realm Map Styling` 3) `Upload Custom .mbtiles` 4) `Custom Deployment`. -::: - -:::warning -Not all Map/Tile providers are fully supported, please check the provider supports MapLibre (see [maplibre providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)). -::: - -The following tile servers have been tested. +## Configuring the Manager UI -| Provider | Supported | Not Supported | -| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -| [Maptiler](https://maptiler.com) | Most standard maps can be imported | | -| [Carto](https://carto.com/) | Basemaps | | -| [Mapbox](https://mapbox.com/) | Tested [Classic Mapbox styles](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles) using `https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=pk.ey...` | Import settings | -| [OpenFreeMap](https://openfreemap.org/) | All maps can be imported | | ---- -sidebar_position: 2 ---- - -# Configuring the Manager UI - -The settings option 'Appearance' can be used in a [custom deployment](custom-deployment.md). You can use it to style your deployment and configure how the pages of the Manager display the assets and attributes in your system. Some of these settings can be changed visually in the user interface, others can be set when selecting the JSON editor. The configuration gets stored in the manager_config file. +The settings option 'Appearance' can be used in a [custom deployment](../deploying/custom-deployment.md). You can use it to style your deployment and configure how the pages of the Manager display the assets and attributes in your system. Some of these settings can be changed visually in the user interface, others can be set when selecting the JSON editor. The configuration gets stored in the manager_config file. In this user guide we will use an example JSON manager_config and give a short description of each section you could include. Note that some pages have a default config that you can overwrite using the manager_config. @@ -53,6 +21,19 @@ By default Superusers (e.g. the 'admin' user of the master realm) will see these ```json { + "realms": { + "default": { + "appTitle": "ACME IoT", + "headers": [ + "map", "assets", "rules", "insights", "language", "users", "roles", "account", "logs", "logout" + ], + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #1b5630; --or-app-color5: #CCCCCC;}", + "logo": "/images/logo.png", + "logoMobile": "/images/logo-mobile.png", + "favicon": "/images/favicon.png", + "language": "en" + } + }, "pages": { "map": { "card": { @@ -234,7 +215,13 @@ By default Superusers (e.g. the 'admin' user of the master realm) will see these } } } - }, + } +} +``` + + +**Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logos are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. +```json "realms": { "default": { "appTitle": "ACME IoT", @@ -246,119 +233,33 @@ By default Superusers (e.g. the 'admin' user of the master realm) will see these "logoMobile": "/images/logo-mobile.png", "favicon": "/images/favicon.png", "language": "en" + }, + "master": { + "appTitle": "ACME Master", + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", + "logo": "/images/logo.png", + "logoMobile": "/images/logo-mobile.png", + "favicon": "/images/logo-favicon.png", + "language": "en" + }, + "clienta": { + "appTitle": "Client A", + "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", + "logo": "/images/clienta-logo.png", + "logoMobile": "/images/clienta-logoMobile.png", + "favicon": "/images/clienta-favicon.png", + "language": "de" } } } ``` +This is what the --or-app-colors look like in the demo deployment: +![Default colors in OpenRemote](img/or-app-colors.jpg) - - -**Map - Card:** -You can set the attributes to exclude (or include) on the top right card of the map when an asset is selected. This can be done for all asset types (by using default), or per asset type (as shown for WeatherAsset). +**Assets - tree:** Exclude asset types from the 'Add asset' dialog. ```json { "pages": { - "map": { - "card": { - "default": { - "exclude": [ - "notes" - ] - }, - "assetTypes": { - "WeatherAsset": { - "exclude": [ - "location", - "notes", - "model", - "manufacturer" - ] - } - } - } - }, -``` -**Map - Marker config:** -This configures how the markers behave. They can either change their colour based on an attribute value (number, boolean, or string), show a label with or without units, and/or show the direction an asset is facing. Note that this part of the config is not in the manager_config used in the manager demo yet. -```json -"markers": { - "ElectricityProducerSolarAsset": { - "attributeName": "energyExportTotal", - "showLabel": true, - "showUnits": true, - "colours": { - "type": "range", - "ranges": [ - { - "min": 0, - "colour": "39B54A" - }, - { - "min": 50, - "colour": "F7931E" - }, - { - "min": 80, - "colour": "C1272D" - } - ] - } - }, - "LightAsset": { - "attributeName": "onOff", - "showLabel": false, - "showUnits": false, - "colours": { - "type": "boolean", - "true": "6ae8fc", - "false": "016170" - } - } - -``` -**Rules - Controls:** -Set which types of rules are available (for users with the correct permissions), and which actions a rule can perform. -```json - "rules": { - "rules": { - "controls": { - "allowedLanguages": ["JSON", "FLOW", "GROOVY"], - "allowedActionTargetTypes": { - "actions": { - "email": [ - "CUSTOM", "USER" - ], - "push": [ - "ASSET", "USER" - ] - } - } - }, -``` -**Rules - When-Then:** -Set which assettypes are excluded from the list of asset types that can be selected in the When-Then rule. Additionally you can set per asset (or all '*') which attributes should be excluded from the select list. -```json - "descriptors": { - "all": { - "excludeAssets": [ - "TradfriLightAsset", - "TradfriPlugAsset", - "ArtnetLightAsset" - ], - "assets": { - "*": { - "excludeAttributes": [ - "location" - ] - } - } - } - } - } - }, -``` -**Assets - tree:** Exclude asset types from the 'Add asset' dialog. -```json "assets": { "tree": { "add": { @@ -381,10 +282,16 @@ Set which assettypes are excluded from the list of asset types that can be selec } } } - }, + } + } + } +} ``` **Assets - viewer:** Configure which panels are shown on the assets page. You can include or exclude attributes to show per panel. These panels can be set for all asset types, or specified per type. This is an overwrite of the default config of the [asset-viewer](https://github.com/openremote/openremote/blob/master/ui/component/or-asset-viewer/src/index.ts). In `historyConfig` an example is given on how to specify the columns shown in a table for an attribute that is not a number or boolean; if no config is given, it will automatically create columns. ```json +{ + "pages": { + "assets": { "viewer": { "assetTypes": { "WeatherAsset": { @@ -489,39 +396,178 @@ Set which assettypes are excluded from the list of asset types that can be selec } } } + } + } +} ``` -**Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logos are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. +**Rules - Controls:** +Set which types of rules are available (for users with the correct permissions), and which actions a rule can perform. ```json - "realms": { - "default": { - "appTitle": "ACME IoT", - "headers": [ - "map", "assets", "rules", "insights", "language", "users", "roles", "account", "logs", "logout" - ], - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #1b5630; --or-app-color5: #CCCCCC;}", - "logo": "/images/logo.png", - "logoMobile": "/images/logo-mobile.png", - "favicon": "/images/favicon.png", - "language": "en" - }, - "master": { - "appTitle": "ACME Master", - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", - "logo": "/images/logo.png", - "logoMobile": "/images/logo-mobile.png", - "favicon": "/images/logo-favicon.png", - "language": "en" - }, - "clienta": { - "appTitle": "Client A", - "styles": ":host > * {--or-app-color2: #F9F9F9; --or-app-color3: #22211f; --or-app-color4: #275582; --or-app-color5: #CCCCCC;}", - "logo": "/images/clienta-logo.png", - "logoMobile": "/images/clienta-logoMobile.png", - "favicon": "/images/clienta-favicon.png", - "language": "de" +{ + "pages": { + "rules": { + "rules": { + "controls": { + "allowedLanguages": ["JSON", "FLOW", "GROOVY"], + "allowedActionTargetTypes": { + "actions": { + "email": [ + "CUSTOM", "USER" + ], + "push": [ + "ASSET", "USER" + ] + } + } + } + } } } } ``` -This is what the --or-app-colors look like in the demo deployment: -![Default colors in OpenRemote](img/or-app-colors.jpg) +**Rules - When-Then:** +Set which assettypes are excluded from the list of asset types that can be selected in the When-Then rule. Additionally you can set per asset (or all '*') which attributes should be excluded from the select list. +```json +{ + "pages": { + "rules": { + "rules": { + "descriptors": { + "all": { + "excludeAssets": [ + "TradfriLightAsset", + "TradfriPlugAsset", + "ArtnetLightAsset" + ], + "assets": { + "*": { + "excludeAttributes": [ + "location" + ] + } + } + } + } + } + } + } +} +``` +**Map - Card:** +You can set the attributes to exclude (or include) on the top right card of the map when an asset is selected. This can be done for all asset types (by using default), or per asset type (as shown for WeatherAsset). +```json +{ + "pages": { + "map": { + "card": { + "default": { + "exclude": [ + "notes" + ] + }, + "assetTypes": { + "WeatherAsset": { + "exclude": [ + "location", + "notes", + "model", + "manufacturer" + ] + } + } + } + } + } +} +``` +**Map - Marker config:** +This configures how the markers behave. They can either change their colour based on an attribute value (number, boolean, or string), show a label with or without units, and/or show the direction an asset is facing. Note that this part of the config is not yet configured in the manager_config of the manager demo. +```json +{ + "pages": { + "map": { + "markers": { + "ElectricityProducerSolarAsset": { + "attributeName": "energyExportTotal", + "showLabel": true, + "showUnits": true, + "colours": { + "type": "range", + "ranges": [ + { + "min": 0, + "colour": "39B54A" + }, + { + "min": 50, + "colour": "F7931E" + }, + { + "min": 80, + "colour": "C1272D" + } + ] + } + } + } + } + } +} +``` +**Map - Clustering config:** +This configures how clustering behaves. Clustering ensures the map page can render assets smoothly even with 40-50 thousand. The clustering option can be disabled, or changed to cluster markers in a smaller radius showing more clusters and changed to start clustering at a certain zoom level. Note that reducing cluster radius or cluster max zoom can have performance impacts. The recommended cluster max zoom level the is Maximal realm zoom level - 2. +```json +{ + "pages": { + "map": { + "clustering": { + "cluster": true, + "clusterRadius": 180, + "clusterMaxZoom": 17 + } + } + } +} +``` +**Map - Legend config:** +This configures what asset types are shown as markers on the map. The legend is enabled by default can be disabled by setting show to false. +```json +{ + "pages": { + "map": { + "legend": { + "show": true + } + } + } +} +``` + +## Map Settings + +If you want to adjust the map styling. You can change the map under Map Settings. Here you have the following options: + +| Method | Description | When to use? | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Style JSON URL | Override the default map settings with a `style.json` URL (e.g. `https://api.example.com/maps/streets/style.json?key=your_key`) from a Map/Tile provider that supports MapLibre (see [providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)). | If you want to configure a different map quickly. | +| Import Style Settings | After configuring a Style JSON URL you can import it to include the layers allowing you to adjust the map styling. You may optionally configure a Tile server URL (to see more of a map). | If you want to be able to edit the map styling in OpenRemote, but also use an external map. | +| Realm Map Styling | You can add GeoJSON based points, lines and shapes from GeoJSON files. For creating GeoJSON files, you can use e.g. https://geojson.io/. For searching existing GeoJSON map layers, you can use https://overpass-turbo.eu/. | If you want to add map layers per realm. | +| Upload Custom `.mbtiles` | The uploaded map will be used instead of the default (see [working on maps](../../developer-guide/working-on-maps#uploading-mbtiles) for more). | If you happen to have an `.mbtiles` file and want to view a different part of the world. | +| Custom Deployment | Configure the map through [custom deployments](../deploying/custom-deployment.md#map-deploymentmap). | If you want full control over the configurations on the server (advanced usage). | + +:::note +OpenRemote picks how to render the map based on the configurations set in the following order: 1) `Style JSON URL` 2) `Import Style Settings` & `Realm Map Styling` 3) `Upload Custom .mbtiles` 4) `Custom Deployment`. +::: + +:::warning +Not all Map/Tile providers are fully supported, please check the provider supports MapLibre (see [maplibre providers](https://github.com/maplibre/awesome-maplibre?tab=readme-ov-file#maptile-providers)). +::: + +The following tile servers have been tested. + +| Provider | Supported | Not Supported | +| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| [Maptiler](https://maptiler.com) | Most standard maps can be imported | | +| [Carto](https://carto.com/) | Basemaps | | +| [Mapbox](https://mapbox.com/) | Tested [Classic Mapbox styles](https://docs.mapbox.com/api/maps/styles/#classic-mapbox-styles) using `https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=pk.ey...` | Import settings | +| [OpenFreeMap](https://openfreemap.org/) | All maps can be imported | | diff --git a/docs/user-guide/deploying/img/or-app-colors.jpg b/docs/user-guide/manager-ui/img/or-app-colors.jpg similarity index 100% rename from docs/user-guide/deploying/img/or-app-colors.jpg rename to docs/user-guide/manager-ui/img/or-app-colors.jpg From e79abdcd2d97fa40230af73aef60dd4fd89e67d5 Mon Sep 17 00:00:00 2001 From: Koen <44117179+Ekhorn@users.noreply.github.com> Date: Thu, 27 Nov 2025 14:29:35 +0100 Subject: [PATCH 3/5] Apply suggestions --- docs/user-guide/manager-ui/appearance.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/manager-ui/appearance.md b/docs/user-guide/manager-ui/appearance.md index 86a9ed51..e9f27dfa 100644 --- a/docs/user-guide/manager-ui/appearance.md +++ b/docs/user-guide/manager-ui/appearance.md @@ -222,6 +222,7 @@ By default Superusers (e.g. the 'admin' user of the master realm) will see these **Realm configuration:** You can set the branding per realm. In the example below you can see how the page title, headers, colors, and logos are set as default (for any new realm created through the UI), as well as for the 'master' and 'clienta' realms. ```json +{ "realms": { "default": { "appTitle": "ACME IoT", @@ -281,7 +282,7 @@ This is what the --or-app-colors look like in the demo deployment: ] } } - } + }openremote } } } @@ -426,7 +427,7 @@ Set which types of rules are available (for users with the correct permissions), } ``` **Rules - When-Then:** -Set which assettypes are excluded from the list of asset types that can be selected in the When-Then rule. Additionally you can set per asset (or all '*') which attributes should be excluded from the select list. +Set which asset types are excluded from the list of asset types that can be selected in the When-Then rule. Additionally you can set per asset (or all '*') which attributes should be excluded from the select list. ```json { "pages": { @@ -515,7 +516,7 @@ This configures how the markers behave. They can either change their colour base } ``` **Map - Clustering config:** -This configures how clustering behaves. Clustering ensures the map page can render assets smoothly even with 40-50 thousand. The clustering option can be disabled, or changed to cluster markers in a smaller radius showing more clusters and changed to start clustering at a certain zoom level. Note that reducing cluster radius or cluster max zoom can have performance impacts. The recommended cluster max zoom level the is Maximal realm zoom level - 2. +This configures how clustering behaves. Clustering ensures the map page can render assets smoothly even with 40-50 thousand assets. The clustering option can be disabled, or changed to cluster markers in a smaller radius showing more clusters and changed to start clustering at a certain zoom level. Note that reducing cluster radius or cluster max zoom can have performance impacts. The recommended cluster max zoom level is Maximum realm zoom level - 2. ```json { "pages": { @@ -530,7 +531,7 @@ This configures how clustering behaves. Clustering ensures the map page can rend } ``` **Map - Legend config:** -This configures what asset types are shown as markers on the map. The legend is enabled by default can be disabled by setting show to false. +This configures what asset types are shown as markers on the map. The legend is enabled by default and can be disabled by setting show to false. ```json { "pages": { From 25c2567566715c4bbd9679d769f2408881ed1f1e Mon Sep 17 00:00:00 2001 From: Koen <44117179+Ekhorn@users.noreply.github.com> Date: Thu, 27 Nov 2025 14:30:46 +0100 Subject: [PATCH 4/5] Fix --- docs/user-guide/manager-ui/appearance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/manager-ui/appearance.md b/docs/user-guide/manager-ui/appearance.md index e9f27dfa..d4487b78 100644 --- a/docs/user-guide/manager-ui/appearance.md +++ b/docs/user-guide/manager-ui/appearance.md @@ -282,7 +282,7 @@ This is what the --or-app-colors look like in the demo deployment: ] } } - }openremote + } } } } From 910983141735681a5437e5fd3cb40ceace10c94e Mon Sep 17 00:00:00 2001 From: Koen <44117179+Ekhorn@users.noreply.github.com> Date: Thu, 27 Nov 2025 15:47:41 +0100 Subject: [PATCH 5/5] Make inline code block Co-authored-by: Wouter Born --- docs/user-guide/manager-ui/appearance.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/manager-ui/appearance.md b/docs/user-guide/manager-ui/appearance.md index d4487b78..6b2d3397 100644 --- a/docs/user-guide/manager-ui/appearance.md +++ b/docs/user-guide/manager-ui/appearance.md @@ -12,7 +12,7 @@ In this user guide we will use an example JSON manager_config and give a short d :::note -By default Superusers (e.g. the 'admin' user of the master realm) will see these styling changes. However, if ```"manager":{"applyConfigToAdmin":false}``` is set in the manager_config, most styling changes will _not_ show. This option can be set so that the 'admin' user is not limited by what is set in the config. +By default Superusers (e.g. the 'admin' user of the master realm) will see these styling changes. However, if `"manager":{"applyConfigToAdmin":false}` is set in the manager_config, most styling changes will _not_ show. This option can be set so that the 'admin' user is not limited by what is set in the config. :::