From eb1b836f90e2f70943b3ad5d9d251a500e51faf9 Mon Sep 17 00:00:00 2001 From: lolodomo Date: Sun, 19 Nov 2023 14:15:51 +0100 Subject: [PATCH] [sitemap] New parameter staticIcon (#2153) * [sitemap] New parameter staticIcon Related to openhab/openhab-core#3735 Signed-off-by: Laurent Garnier * Review comment: choosing the icon Signed-off-by: Laurent Garnier --------- Signed-off-by: Laurent Garnier --- ui/sitemaps.md | 52 ++++++++++++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/ui/sitemaps.md b/ui/sitemaps.md index 43dfb34143..5d922c86a4 100644 --- a/ui/sitemaps.md +++ b/ui/sitemaps.md @@ -38,7 +38,7 @@ sitemap demo label="My home automation" { Switch item=Lights icon="light" Text item=LR_Temperature label="Livingroom [%.1f °C]" Group item=Heating - Text item=LR_Multimedia_Summary label="Multimedia [%s]" icon="video" { + Text item=LR_Multimedia_Summary label="Multimedia [%s]" staticIcon="video" { Selection item=LR_TV_Channel mappings=[0="off", 1="DasErste", 2="BBC One", 3="Cartoon Network"] Slider item=LR_TV_Volume } @@ -82,7 +82,7 @@ Frame label="Demo" { Switch item=Lights icon="light" Text item=LR_Temperature label="Livingroom [%.1f °C]" Group item=Heating - Text item=LR_Multimedia_Summary label="Multimedia [%s]" icon="video" { + Text item=LR_Multimedia_Summary label="Multimedia [%s]" staticIcon="video" { Selection item=LR_TV_Channel mappings=[0="off", 1="DasErste", 2="BBC One", 3="Cartoon Network"] Slider item=LR_TV_Volume } @@ -99,7 +99,7 @@ Different elements can be used on the previous or next hierarchy level. When using code blocks behind other element types such as `Text` or `Group`, these UI elements will, in addition to their normal function, be links to a new view, presenting the nested elements. ```java -Text item=LR_Multimedia_Summary label="Multimedia [%s]" icon="video" { +Text item=LR_Multimedia_Summary label="Multimedia [%s]" staticIcon="video" { Selection item=LR_TV_Channel mappings=[0="off", 1="DasErste", 2="BBC One", 3="Cartoon Network"] Slider item=LR_TV_Volume } @@ -176,11 +176,13 @@ This provides the flexibility to present Items in the way desired in your home a - Common parameters, also known from [items definition]({{base}}/configuration/items.html#item-syntax): - `item` defines the name of the Item you want to present (e.g. `Temperature`), [more details]({{base}}/configuration/items.html#item-name). - `label` sets the textual description displayed next to the preprocessed Item data (e.g. "`Now [%s °C]`"), [more details]({{base}}/configuration/items.html#item-label). - - `icon` chooses the name of the icon file to show next to the element, [more details]({{base}}/configuration/items.html#icons). + - `icon` chooses the icon to show next to the element, [more details]({{base}}/configuration/items.html#icons). - When an [Item]({{base}}/configuration/items.html) is defined, you have the opportunity to assign a label and/or an icon at that point. If no label or icon are specified in the Sitemap, then the label and/or icon you assigned to the Item will be displayed. - Setting a value for `label` or `icon` of a Sitemap element will override the values defined for the linked Item. + Setting a value for `label` or `icon` or `staticIcon` of a Sitemap element will override the values defined for the linked Item. + +- The parameters `icon` and `staticIcon` are exclusive; both allow choosing the icon to show next to the element but `staticIcon` also indicates not to try to create a dynamic icon (using the current state of a linked item). The value of these two parameters can optionally be enclosed in double quotes. It has to be considered that if the label defined in a Channel or an Item contains text and state, these representations have to be overwritten separately in the Sitemap. In the following example an Item which has a label and state defined is overwritten. @@ -207,7 +209,7 @@ UoM = [Units of Measurement]({{base}}/concepts/units-of-measurement.html) ### Element Type 'Frame' ```java -Frame [label=""] [icon=""] { +Frame [label=""] [icon=] [staticIcon=] { [additional sitemap elements] } ``` @@ -228,7 +230,7 @@ Frame label="Demo" { ### Element Type 'Default' ```java -Default item= [label=""] [icon=""] +Default item= [label=""] [icon=] [staticIcon=] ``` Presents an Item using the default UI representation specified by the type of the given Item. @@ -237,7 +239,7 @@ E.g., a `Dimmer` Item will be represented as a [Slider](#element-type-slider) el ### Element Type 'Text' ```java -Text [item=] [label=""] [icon=""] +Text [item=] [label=""] [icon=] [staticIcon=] ``` Presents data as normal text. @@ -247,7 +249,7 @@ Please refer to the documentation on [item State Presentation]({{base}}/configur **Example:** ```java -Text item=Temperature label="Livingroom [%.1f °C]" icon="temperature" +Text item=Temperature label="Livingroom [%.1f °C]" staticIcon=temperature ``` ![Presentation of the Text element in BasicUI](images/sitemap_demo_text.png) @@ -255,7 +257,7 @@ Text item=Temperature label="Livingroom [%.1f °C]" icon="temperature" ### Element Type 'Group' ```java -Group item= [label=""] [icon=""] +Group item= [label=""] [icon=] [staticIcon=] ``` Clicking on a Group element will reveal a new view showing all group items using the [Default](#element-type-default) element type. @@ -279,7 +281,7 @@ Group item=gTemperature label="Room Temperatures [%.1f °C]" ### Element Type 'Switch' ```java -Switch item= [label=""] [icon=""] [mappings=""] +Switch item= [label=""] [icon=] [staticIcon=] [mappings=""] ``` Switches are one of the more common elements of a typical Sitemap. @@ -292,7 +294,7 @@ Note that Switch elements can be rendered differently on the user interface, bas **Examples:** ```java -Switch item=LR_CeilingLight label="Ceiling Light" icon="light" +Switch item=LR_CeilingLight label="Ceiling Light" icon=light Switch item=LR_TV_Channel label="TV Channel" mappings=[0="DasErste", 1="BBC One", 2="Cartoon Network"] ``` @@ -302,7 +304,7 @@ Switch item=LR_TV_Channel label="TV Channel" mappings=[0="DasErste", 1="BBC One" ### Element Type 'Selection' ```java -Selection item= [label=""] [icon=""] [mappings=""] +Selection item= [label=""] [icon=] [staticIcon=] [mappings=""] ``` The Selection element type renders the options as a dropdown menu or as a modal dialog prompt, depending on the user interface. @@ -321,7 +323,7 @@ Selection item=LR_TV_Channel label="TV Channel" mappings=[0="DasErste", 1="BBC O ### Element Type 'Setpoint' ```java -Setpoint item= [label=""] [icon=""] minValue= maxValue= step= +Setpoint item= [label=""] [icon=] [staticIcon=] minValue= maxValue= step= ``` - `minValue` (defaults to 0) and `maxValue` (defaults to 100) limit the possible range of the value (both included in the range). @@ -338,7 +340,7 @@ Setpoint item=KI_Temperature label="Kitchen [%.1f °C]" minValue=4.5 maxValue=30 ### Element Type 'Slider' ```java -Slider item= [label=""] [icon=""] [sendFrequency="frequency"] [switchSupport] [minValue=] [maxValue=] [step=] +Slider item= [label=""] [icon=] [staticIcon=] [sendFrequency="frequency"] [switchSupport] [minValue=] [maxValue=] [step=] ``` This type presents a value as a user-adjustable control which slides from left (0) to right (100). @@ -364,7 +366,7 @@ Slider item=KI_Temperature label="Kitchen" ### Element Type 'Colorpicker' ```java -Colorpicker item= [label=""] [icon=""] [sendFrequency=] +Colorpicker item= [label=""] [icon=] [staticIcon=] [sendFrequency=] ``` This element is a combined control for something like a rgb or rgbw light where you can adjust brightness as well es the color hue. @@ -377,7 +379,7 @@ The middle button opens an overlay to finetune your color. A color wheel let you **Example:** ```java -Colorpicker item=LR_LEDLight_Color label="LED Light Color" icon="colorwheel" +Colorpicker item=LR_LEDLight_Color label="LED Light Color" staticIcon=colorwheel ``` ![Presentation of the Colorpicker element in BasicUI](images/sitemap_demo_colorpicker.png) @@ -385,7 +387,7 @@ Colorpicker item=LR_LEDLight_Color label="LED Light Color" icon="colorwheel" ### Element Type 'Input' ```java -Input item= [label=""] [icon=""] [inputHint=""] +Input item= [label=""] [icon=] [staticIcon=] [inputHint=""] ``` This element allows entering of text, numbers and dates/times and updating the underlying items. @@ -401,7 +403,7 @@ Note that this element type may not be supported on all user interfaces that sup **Example:** ```java -Input item=Meter_Reading label="Meter [%.0f %unit%]" icon="energy" inputHint="number" +Input item=Meter_Reading label="Meter [%.0f %unit%]" staticIcon=energy inputHint="number" ``` ![Presentation of the Input element in BasicUI](images/sitemap_demo_input.png) @@ -409,7 +411,7 @@ Input item=Meter_Reading label="Meter [%.0f %unit%]" icon="energy" inputHint="nu ### Element Type 'Webview' ```java -Webview item= [label=""] [icon=""] url="" [height=] +Webview item= [label=""] [icon=] [staticIcon=] url="" [height=] ``` The content of a webpage will be presented live on your user interface next to other Sitemap elements. @@ -428,7 +430,7 @@ Webview url="https://www.openhab.org" height=5 ### Element Type 'Mapview' ```java -Mapview [item=] [label=""] [icon=""] [height=] +Mapview [item=] [label=""] [icon=] [staticIcon=] [height=] ``` Displays an [OSM](https://www.openstreetmap.org) map based on a given Location Item. @@ -446,7 +448,7 @@ Mapview item=Demo_Location height=5 ### Element Type 'Image' ```java -Image [item=] [icon=""] url="" [label=""] [refresh=xxxx] +Image [item=] [icon=] [staticIcon=] url="" [label=""] [refresh=xxxx] ``` This element type is able to present an image. @@ -471,7 +473,7 @@ Image url="https://192.168.1.203:8080/?action=snapshot" refresh=10000 ### Element Type 'Video' ```java -Video [item=] [icon=""] url="" [encoding="