Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[sitemap] New parameter staticIcon #2153

Merged
merged 4 commits into from
Nov 19, 2023
Merged

[sitemap] New parameter staticIcon #2153

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d3b8d3
[sitemap] New parameter staticIcon
lolodomo Nov 12, 2023
90f9e15
Review comment: choosing the icon
lolodomo Nov 18, 2023
1931d67
Merge branch 'main' into sitemap_staticIcon
lolodomo Nov 19, 2023
aa0c630
Merge branch 'main' into sitemap_staticIcon
lolodomo Nov 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 27 additions & 25 deletions ui/sitemaps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down Expand Up @@ -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
}
Expand All @@ -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
}
Expand Down Expand Up @@ -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.
Expand All @@ -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]
}
```
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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"]
```

Expand All @@ -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.
Expand All @@ -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).
Expand All @@ -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).
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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]
```

Expand Down Expand Up @@ -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
}
Expand Down