[sitemap] New parameter staticIcon (#2153)

* [sitemap] New parameter staticIcon

Related to openhab/openhab-core#3735

Signed-off-by: Laurent Garnier <lg.hc@free.fr>

* Review comment: choosing the icon

Signed-off-by: Laurent Garnier <lg.hc@free.fr>

---------

Signed-off-by: Laurent Garnier <lg.hc@free.fr>

Author: lolodomo

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="<labelname>"] [icon="<icon>"] {
+Frame [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] {
     [additional sitemap elements]
 }
 ```
@@ -228,7 +230,7 @@ Frame label="Demo" {
 ### Element Type 'Default'
 
 ```java
-Default item=<itemname> [label="<labelname>"] [icon="<iconname>"]
+Default item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>]
 ```
 
 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=<itemname>] [label="<labelname>"] [icon="<iconname>"]
+Text [item=<itemname>] [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>]
 ```
 
 Presents data as normal text.
@@ -247,15 +249,15 @@ 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)
 
 ### Element Type 'Group'
 
 ```java
-Group item=<itemname> [label="<labelname>"] [icon="<iconname>"]
+Group item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>]
 ```
 
 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=<itemname> [label="<labelname>"] [icon="<iconname>"] [mappings="<mapping definition>"]
+Switch item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [mappings="<mapping definition>"]
 ```
 
 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=<itemname> [label="<labelname>"] [icon="<iconname>"] [mappings="<mapping definition>"]
+Selection item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [mappings="<mapping definition>"]
 ```
 
 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=<itemname> [label="<labelname>"] [icon="<iconname>"] minValue=<min value> maxValue=<max value> step=<step value>
+Setpoint item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] minValue=<min value> maxValue=<max value> step=<step value>
 ```
 
 - `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=<itemname> [label="<labelname>"] [icon="<iconname>"] [sendFrequency="frequency"] [switchSupport] [minValue=<min value>] [maxValue=<max value>] [step=<step value>]
+Slider item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [sendFrequency="frequency"] [switchSupport] [minValue=<min value>] [maxValue=<max value>] [step=<step value>]
 ```
 
 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=<itemname> [label="<labelname>"] [icon="<iconname>"] [sendFrequency=<sendFrequency>]
+Colorpicker item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [sendFrequency=<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,15 +379,15 @@ 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)
 
 ### Element Type 'Input'
 
 ```java
-Input item=<itemname> [label="<labelname>"] [icon="<iconname>"] [inputHint="<inputHint>"]
+Input item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [inputHint="<inputHint>"]
 ```
 
 This element allows entering of text, numbers and dates/times and updating the underlying items.
@@ -401,15 +403,15 @@ 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)
 
 ### Element Type 'Webview'
 
 ```java
-Webview item=<itemname> [label="<labelname>"] [icon="<iconname>"] url="<url>" [height=<heightvalue>]
+Webview item=<itemname> [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] url="<url>" [height=<heightvalue>]
 ```
 
 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=<itemname>] [label="<labelname>"] [icon="<iconname>"] [height=<heightvalue>]
+Mapview [item=<itemname>] [label="<labelname>"] [icon=<iconref>] [staticIcon=<iconref>] [height=<heightvalue>]
 ```
 
 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=<itemname>] [icon="<iconname>"] url="<url of image>" [label="<labelname>"] [refresh=xxxx]
+Image [item=<itemname>] [icon=<iconref>] [staticIcon=<iconref>] url="<url of image>" [label="<labelname>"] [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=<itemname>] [icon="<iconname>"] url="<url of video to embed>" [encoding="<video encoding>"]
+Video [item=<itemname>] [icon=<iconref>] [staticIcon=<iconref>] url="<url of video to embed>" [encoding="<video encoding>"]
 ```
 
 Allows you to display a video as part of your Sitemap.
@@ -496,7 +498,7 @@ Video url="https://demo.openhab.org/Hue.m4v"
 ### Element Type 'Chart'
 
 ```java
-Chart item=<itemname> [icon="<iconname>"] [label="<labelname>"] [refresh=xxxx]
+Chart item=<itemname> [icon=<iconref>] [staticIcon=<iconref>] [label="<labelname>"] [refresh=xxxx]
 period=xxxx [service="<service>"] [legend=true/false] [forceasitem=true/false] [yAxisDecimalPattern=xxxx]
 ```
 
@@ -721,7 +723,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
         }