openhab/openhab — pull request #57 by cdjackson (2013-10-26 11:27:26+00:00)
Title: Sitemap/UI enhancements (dynamic sitemaps / chart servlet)

This contains a number of (mostly) small fixes in the sitemap/ui area primarily to add dynamic sitemap features, and a chart servlet. The changes generally apply to all widgets to add color, icons and visibility "rules".
There are some implementation questions at the bottom and I'm happy to make changes if you think things should be done differently (especially with the xtext as I'm not especially familiar with that!).

1) Dynamic Colors (**Issue 317**)
Colors have been added to "all" widget components - icon, label and value (labelcolor/iconcolor/valuecolor). Each can be specified individually, and they can be a static value (eg. labelcolor=[green]), or a conditional array of colors (eg iconcolor=[ON=green, OFF=red]). The conditional test is against the item defined in the widgets item= tag, and numeric values are tested as > so ordering of the list is important.

2) Dynamic Icons
Similar to (and the logical extension to) colors, icons can now be changed dynamically. The existing static icon can still be used (eg icon="temperature"), but you can now add a dynamic array of icons (eg icon="30=temperature_high, 20=temperature_norm, 10=temperature_low"). The test is against the item defined in the widgets item= tag. See my comments on this in the issues list below - I'm thinking that this should be implemented as iconarray=[..] to make the format consistent with the other changes (ie colors, visibility).

3) Widget dynamic visibility (**Issue 118**)
Widgets can now have a visibility rule applied. By default, a widget is visible, but you can add the rule to make it hidden (eg visibility=[Heating=ON]).
Multiple "rules" can be added, and the "rule" is simply an item name and a state. If any rule returns true, the item will be visible, otherwise it will be hidden. Each rule can use a different item - so you could have "show the temperature control if temperature is below 10 or heating is on" -
item=temperature_button visibility=[Temperature=10, Heating=ON]. Note that numeric values are tested as >, not as =.

4) Dynamic URLs (Image/Video) (**Issue 310**)
Widgets with URLs can now have the URL dynamically changed based on an items state. The existing url="address" is retained, and will be the default URL if none of the conditional URLs meet the conditional test. An additional conditional URL array is now defined to account for the dynamic content (eg urlarray=[ON="address-when-on.com", OFF="address-when-off.com"]. The test is against the item defined in the widgets item= tag.

5) Updated sitemap tag (**Issue 328**)
I've added icon and label to sitemap list

6) Removed quotes in mapping (**Issue 483**)
If the mappings name is surrounded by quotes, these are removed
(eg mappings=[HDMI1=Computer, HDMI2=PS3, "NET RADIO"="NET RADIO"])

7) Caught exception caused by number format error.
There is a bug in JDK that can cause a format exception - it seems to happen if you have 0.00000! This caused the whole sitemap to not be displayed. This is caught and "Err" is presented to the user.

8) I've added a new chart servlet "/chart". This has been discussed in the group, so you should be happy with the new interface. I also added a default chart provider which renders simple charts (probably not too dissimilar to the rrd charts).
This is all defined in org.openhab.ui.

---
**Questions/issues**
* Unfortunately there are a couple of files that GitHub shows as changed completely. I don't know why this is, and I can't seem to change it (same problem we both had with the HistoricState merge last week). An external diff shows the changed lines ok, but GitHub says everything has changed :(
* I have an open question with the use of "icon" in Widgets. Currently this is a single string that I process in the ItemUIRegistryImpl to be either an array or single icon string (as it is by default). This does mean that the icon array definition is slightly different to the other definitions (eg colors) which are processed by xtext. I am thinking about changing this to be the same, and add a new attribute - the same as I've done for the url (maybe iconarray=[...]).

---
**Overview of Sitemap additions**
This is split between changes to the sitemap model (all additions - it should not impact backward compatibility) and the REST interface.
Note that some of these don't work with the current GUIs, but they also don't cause any problems since it is generally an additional field in the REST interface to provide color. I know Mihail (@mishoboss) is planning to change GreenT and I have modified HABDroid to support the colors and the new chart servlet (https://github.com/cdjackson/HABDroid). HABDroid nicely supports the dynamic visibility out of the box (it's very nice I think) and the other features (dynamic icons, urls) should not require client side changes.

labelcolor=[state="color", "state="color"]
iconcolor=[state="color", "state="color"]
valuecolor=[state="color", "state="color"]

These allow setting of the label, the value and the icon colors respectively. For numeric values, the comparison is done as a greater than, so you should list the values in DESCENDING order for it to work correctly.
These can also be set to a static color using iconcolor=["green"].
Colors are passed as written to the REST interface to be processed by the GUI. Generally, this means you can use standard HTML colors (red, green, yellow etc, as well as the #00ff6633 style).
For dates, the value is compared to current time, and the value is in seconds. For example, to make a date go yellow after it is older than 600 seconds, use iconcolor=[600="yellow"]

icon="icon"
icon="state=icon1, state2=icon2"

This sets the icon to a different icon depending on the item state. Note that the format is slightly different to the others as I was having a fight with the xtext parser! I might change this in future and welcome your comments on this.

visibility=[item=state, item=state]

This allows changing the visibility of the widget. Here you can specify a list of items and states - if ANY of the conditions are true, the widget will be visible.

For image and video widgets, the following is also possible
urlarray=[state="url, state="url"]

The same rule is applied as for the colors, but this time the URL is changed depending on the value of the item. The existing url="" is still available and it is used as a default if none of the conditions are met.
It is also possible to set the "url" to the value of a stringitem. This should be possible for url statements as it is checked after evaluating the conditional array. For this to work, the check is made against the url to see if it is a stringitem, and a valid item name.

---
**A few examples**
Text item=Outside_RainGauge_LastUpdate valuecolor=[10800="red", 3600="yellow", 0="green"]
This will set the last update indicator to show red if the value is older than 3 hours and yellow if older than 1 hour - green otherwise.

Text item=Outside_RainGauge_Battery valuecolor=[2.9="green", 2.7="yellow", 2.6="red"]
Similar for battery voltage

Setpoint item=HallThermostat_SetTemp label="Hall Setpoint [%d Â°C]" minValue=14 maxValue=25 step=1 visibility=[HallThermostat_Enable=ON]
Switch item=HallThermostat_HWEnable label="Hot Water Enable" visibility=[HallThermostat_Enable=ON]
This will only show the hot water enable switch and temperature setpoint if the hall thermostat is ON (since hot water is controlled by this thermostat).