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

Sitemap: extended syntax for icon to define conditional rules #2175

Merged
merged 2 commits into from
Dec 16, 2023
Merged

Sitemap: extended syntax for icon to define conditional rules #2175

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
10792c0
Sitemap: extended syntax for icon to define conditional rules
lolodomo Dec 16, 2023
0dc76d1
Considers review comments
lolodomo Dec 16, 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
49 changes: 43 additions & 6 deletions ui/sitemaps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -631,7 +631,7 @@ Colors can be used to emphasize an items label or its value based on conditions.
Colors may be assigned to either the label or the value associated with an Item.
The icon may be tinted depending on the state as well.

**Label and Value Color Syntax:**
**Label, Value and Icon Color Syntax:**

```java
labelcolor=[item_name operator value = "color", item_name operator value AND item_name operator value = "color", ... ]
Expand All @@ -650,7 +650,7 @@ If `item_name` is not provided, the Item name will default to the current Item.
If an operator is not specified, the operator will default to `==`.

If only a color is specified, that condition is considered as true and that color will be used.
It can be used as a last condition to set a default color that will be used in case any of the other previous conditions is true.
Providing only a color can be used as a last condition to set a default color that will be used in case any of the other previous conditions is true.

The comparison operators for `labelcolor`, `valuecolor` and `iconcolor` are the same as for the visibility parameter.

Expand Down Expand Up @@ -721,12 +721,49 @@ There are also the following keywords that can be used as colors:
### Icons

openHAB allows a set of icons to be assigned to the different states of an Item and therefore to be presented in a Sitemap.
This first way of proceeding only considers the current state of the linked item and requires the use of icons provided by openHAB and a particular syntax of icon names.
Please refer to the documentation on [Item configuration]({{base}}/configuration/items.html#icons) for details.

![battery-0](/iconsets/classic/battery-0.png "battery-0")
![battery-30](/iconsets/classic/battery-30.png "battery-30")
![battery-60](/iconsets/classic/battery-60.png "battery-60")
![battery-100](/iconsets/classic/battery-100.png "battery-100")
![battery-0](/iconsets/classic/battery-0.svg "battery-0")
![battery-30](/iconsets/classic/battery-30.svg "battery-30")
![battery-60](/iconsets/classic/battery-60.svg "battery-60")
![battery-100](/iconsets/classic/battery-100.svg "battery-100")

There is also a more powerful way to define a dynamic icon based on the states of different items and allowing you to attach any type of icon regardless of its source (not restricted to icons provided by openHAB).

The `icon` parameter can be used to provide conditional rules.

Extended icon syntax:

```java
icon=[item_name operator value = icon, item_name operator value AND item_name operator value = icon, ... ]
```

You can set as many conditions as you want, along with a reference to an icon for each condition.

A condition can be a single comparison or a combination of several comparisons all separated by the AND operator.
A condition including the AND operator will be considered as true if all individual comparisons are considered as true.
Of course, it is possible to reference a different item in each comparison.

Note that `item_name` and `operator` are both optional.
If `item_name` is not provided, the Item name will default to the current Item.
If an operator is not specified, the operator will default to `==`.

Conditions are evaluated from left to right; the first matching condition determines the icon.
If only a reference to an icon is specified, that condition is considered as true and that icon will be used.
Providing only a reference to an icon can be used as a last condition to set a default icon that will be used in case any of the other previous conditions is true.

The comparison operators are the same as for the visibility parameter.

**Examples:**

The following three lines are equivalent.

```java
Text item=TemperatureTrend icon=["UP"=f7:arrowtriangle_up, "DOWN"=f7:arrowtriangle_down, f7:arrowtriangle_right]
Text item=TemperatureTrend icon=[=="UP"=f7:arrowtriangle_up, =="DOWN"=f7:arrowtriangle_down, f7:arrowtriangle_right]
Text item=TemperatureTrend icon=[TemperatureTrend=="UP"=f7:arrowtriangle_up, TemperatureTrend=="DOWN"=f7:arrowtriangle_down, f7:arrowtriangle_right]
```

## Full Example

Expand Down