A curated list of units to show as a drop-down list when creating a Number item with dimension.
The possibility to use a different default unit on item creation than the system default unit.
The ability to change unit and state description for items.
By default, the system default unit (for the configured measurement system) will be shown when editing or creating an item. units.js contains a number of frequently used units by dimension and measurement system. These will be available in a autosuggest dropdown list. It is still possible to not select from the list and use any other string as a unit. units.js now only contains a relatively small list, but can easily be extended with other frequently used units.
All units for the dimension in units.js will be in the dropdown list, but they will be sorted by measurement system. If the measurement system is set to US, imperial units will appear higher in the list. Units that have not explicitely been listed as SI or US will always appear higher.
When typing a unit that is not in the curated list, a longer list will be used for autocompletion that considers allowed prefixes to base units and constructs all combinations.
units.js also contains a field to set a different default unit on item creation than the system default unit.
If such information is available, this PR adds support for this in the UI. When creating an item from a thing channel, it will suggest to use the unit from the unit hint if available. If not available, it will suggest the webui defined default from units.js, if not available, the system default unit for the dimension.
For dimensions with different units in SI or US measurement systems, it is possible to provide 2 units separated by comma in binding channel types. The first one will be SI, the second US. The suggested one will depend on the measurement system setting.
I will make a build and test how it looks on screen
Ok. I did a full build and found three problems..
Item Creation: Initially when I first tried to create an item attached to a channel with unitHint, the 'Unit' and 'State Description Pattern' fields could not be selected, and thus could not be edited i.e. they were read only. But after some time playing around with creating and deleting items, when I tried to create an item again, the fields became editable once more. I was using the Chrome browser so I wonder if it may have been related to the recently posted browser cache issue -- but perhaps not. I tried it also in Edge and did not see the same issue.
Item Editing: When editing the (already created) item the respective input page does not display the 'Unit' or 'State Description Pattern' fields. So to change an already existing item, the only solution is to delete and recreate the item.
For the respective channel item shown in the screenshots above, I had set unitHint="dB" in the respective binding, however the input screen in the browser showed 'one'..
^
Apropos point 3. above, I can see the "unitHint=dB" in the REST API JSON provided by OH core.
So in other words, the issue seems to be in openhab-webui rather than openhab-core..
{
"parameters": [],
"parameterGroups": [],
"description": "Quality of Service: percentage of configured devices currently connected to the RF mesh network",
"label": "Mesh Network QoS",
"itemType": "Number:Dimensionless",
"unitHint": "dB",
"kind": "STATE",
"stateDescription": {
"pattern": "%.0f %%",
"readOnly": true,
"options": []
},
"tags": [],
"UID": "neohub:meshNetworkQoS",
"advanced": false
},
@florian-h05 While this PR now will benefit of https://github.com/openhab/openhab-core/pull/4079 and provide extra functionality, it is not strictly required for this PR and will work without.
There are more ways of providing more meaningful unit suggestions in the PR now.
For Temperature, can someone in SI still pick °F?
An idea for consideration: instead of excluding the "other" units, perhaps put them after the preferred units, so for people using SI, they'll get SI units first, followed by US units, and vice versa...?
An idea for consideration: instead of excluding the "other" units, perhaps put them after the preferred units, so for people using SI, they'll get SI units first, followed by US units, and vice versa...?
Possible, but from a perspective of a European, I don't want to see the Imperial units. I don't deal with them at all. That perspective could be different for users in the US though.
From usability perspective, when it's not there, some people might think it's not possible.
Agree, but I don't see a good way to overcome it. The issue is there are too many combinations possible for units and their multipliers. Showing them all does not make sense. And if you don't show all possible combinations, the proposed list should be relevant with the possiblity to put something else if needed. That's what I try to achieve.
@rkoshak Your opinion on this would be valued as well.
They might need to use metric sometimes, and at that time, having the hints would probably be quite helpful. I'm happy either way
Please just remember the poor old UK ..
.. unlike the US which uses 'Imperial' (I always find it odd that the US refers to its units by reference its one-time imperial over-lords) .. the UK has mostly adopted SI and dropped 'Imperial' (Brexit notwithstanding) .. EXCEPT in a couple of peculiar special cases -- namely as follows..
On the road: where distance and speed are measured in miles, fuel is sold in litres, and consumption is measured in miles-per-gallon (sic) .. and note that UK 'Imperial' gallons are different from US 'Imperial' gallons .. go figure ..
In the pub: where beer is sold in pints..
=> Ergo for UK users, presenting both units, would probably make sense..
Ummm. It gets complicated. See below. .. Please, please, please don't ask me why
The British Imperial fluid ounce is equal to 28.413 milliliters, while the US Customary fluid ounce is 29.573 ml.
The British Imperial pint is 568.261 ml (20 fluid ounces), while the US Customary pint is 473.176 ml (16 fl oz).
The British Imperial quart is 1.13 liters (40 fl oz), while the US Customary quart is 0.94 L (32 fl oz).
The British Imperial gallon is 4.54 L (160 fl oz), while the US Customary gallon is 3.78 L (128 fl oz).
I won't ask. I was just wondering what conversion OH is using if you convert between the units using QuantityTypes. This can get messy fast. What if you put in volume liters for how much you put in your car tank (so an item with unit liter), have the distance that your car travelled in miles (an item with unit miles) and a rule that calculats consumption (distance/volume) and show it in miles/gallon (state description for resulting item). What conversion will OH use for this? US? British? If it is US, the system doesn't work for UK, or? And to me that would be an argument not to show units from the other measurement system. They are always available by typing them in.
That perspective could be different for users in the US though.
People in the US do use metric almost day to day. It's really just that the government decided it wasn't worth the cost to force it's use. So we buy our milk in gallons but buy our Cokes in two liter bottles. Our cars travel miles but the bolts that hold them together are often in mm. It often depends on context which type of unit is used. But the units are kind of unofficially standardized. You won't see milk sold in liters nor Cokes sold in gallons. So we are not very good at switching between the two for the same thing. Forecast that it's going to be -3 °C and people will be confused.
Anyway, that's a long way of saying showing both for US users wouldn't be a problem and in some rare cases the metric will be preferred over the Imperial unit. We're not that far off from the UK in that regard.
Anyway, back to why I as tagged...
From usability perspective, when it's not there, some people might think it's not possible.
I understand both sides here. There are far too many units to present in one list. OTH, it may not be clear that in cases where the unit isn't in the list that the user can just type it in. I've seen people become confused by this in Item Triggers in Rules. They see this
And become confused about why there's that ON/OFF toggle, can an Item only trigger a rule with ON and OFF?
So in the description we need to make it absolutely clear that the field is editable and to edit it when the desired unit isn't in the list. If there are hints in the description of the field as well as some UI hints (e.g. a blinking cursor in the field when it's clicked on perhaps) that may be as good as we can go it.
This is a little bit out there, but would it make sense to create a "unit builder" akin to the cron builder? Then instead of a giant list, the user can "build" the unit. They could select the Dimension, then select from the list of those units the Dimension supports (that list at least will be short) and finally select a scale modifier, if supported.
So to get to kWh for example the user would select Energy for the Dimension, Wh for the unit from the list of only those units that Energy supports (J, Ws, Wm, Wh, VAh, varh, and cal) and then kilo for the scale modifier. For density and speed type units there can be an optional "per" field (e.g. Bq/m³, mph, etc.). It's just a half thought out idea. I was just thinking that if we could split the list so the user doesn't have to sort through everything all at once it might be more workable to present most of the units or at least a bigger set of the units. It's probably significantly more work though.
If understand correctly, that's the whole point of this PR.
When "Length" dimension is selected, users will be given the list of length units only. So this may not be as long as you may think. Plus this PR is about curating only the common units, so it's even shorter than the list of all possible units.
I tagged a specific post, but actually am happy you comment on the overall discussion. Thank you.
This is a little bit out there, but would it make sense to create a "unit builder" akin to the cron builder?
Yes, definitely a lot more work, and note it makes selecting a unit a longer process as well. There suddenly is another screen with multiple parameters to set. I am not prepared to try to do that with this PR.
If understand correctly, that's the whole point of this PR.
When "Length" dimension is selected, users will be given the list of length units only. So this may not be as long as you may think. Plus this PR is about curating only the common units, so it's even shorter than the list of all possible units.
I am afraid it is longer than you think. If you look at @rkoshak example, you have a set of base units (J, Ws, Wm, Wh, VAh, varh, and cal), but these are not even exhaustive. Notice Ws, Wh, VAh, ... are already multiplied units. In theory, other combinations would be possible. And then there are all the possible modifiers in front.
The idea of the PR is to give a reasonable list, not a full list. Notice I have not even attempted to provide units for everything.
So in the description we need to make it absolutely clear that the field is editable and to edit it when the desired unit isn't in the list. If there are hints in the description of the field as well as some UI hints (e.g. a blinking cursor in the field when it's clicked on perhaps) that may be as good as we can go it.
We can't put a Any placeholder, because it will always be filled with a default already. But I can extend the info text to try to make it clearer.
Yes, definitely a lot more work, and note it makes selecting a unit a longer process as well. There suddenly is another screen with multiple parameters to set.
But not longer for those who just know what to type in.
Anyway, it was just an idea.
are already multiplied units. In theory, other combinations would be possible. And then there are all the possible modifiers in front.
I wasn't trying to suggest that the builder be exhaustive to support every possible combination of every possible unit. There can be some really complicated units for sure (Bq/m³ would probably be among them and was probably a bad example to list above).
I was just thinking that kilo is k whether you are talking about b or Wh or l. If you made setting that part separate you wouldn't have to include them in a list. Complicated stuff like Ws vs. Wm, well those are listed separately in the docs already so just treat them as separate units in the tool.
But again, it was just an idea, not even a request.
^
The current behaviour is that OH offers for the respective dimensionjust one single choice of unit only -- namely the 'default' unit. But yes you can override that one single choice by manually typing in something else.
The purpose of this PR is to offer for the respective dimension a curated selection of units. And yes you can choose something else by manually typing it in.
I've seen people become confused by this in Item Triggers in Rules. They see this
And become confused about why there's that ON/OFF toggle, can an Item only trigger a rule with ON and OFF?
I'll admit it wasn't my best design, the intent was to present the actual input control, and then below it quick & easy suggestions for the value. So the suggestions are just that and don't prevent you from inputting whatever you want in the textbox.
This is a little bit out there, but would it make sense to create a "unit builder" akin to the cron builder? Then instead of a giant list, the user can "build" the unit. [...]
So to get to kWh for example the user would select Energy for the Dimension, Wh for the unit from the list of only those units that Energy supports (J, Ws, Wm, Wh, VAh, varh, and cal) and then kilo for the scale modifier.
Certainly interesting, as long as it's not a pain to use. If you want your energy measurement in Wh or kWh you should just have to type "Wh" or "kWh" into a textbox and be done with it without dealing with a "unit builder" UI. The cron builder allows that so I would expect an unit builder would too.
I don't feel comfortable creating a real unit builder.
But an alternative could be the following:
When creating an item, the unit field will default as in the current PR state (unitHint, default from UI default, system default).
Dropdown (autosuggest) on the field shows the curated list.
Start typing, and you get all possible combinations for completion. E.g. if you are in an Energy dimension item, start typing k, you will get as suggestion kWs, kWh, kVAh, kvarh, kJ, kcal (and possibly others). This would not be restricted to the curated list.
What is needed for the last part, is code to create a list of valid options (beyond the currated one), and as complete as possible. Would there be any js library that could be included for that? Anyway, if someone wants to build a unit builder, something similar would be required.
TLDR summary: LGTM when creating a new item for a channel; but not working when editing that same (already created) item.
A. Create New Item for Channel
Type => Ok
Dimension => Ok
Unit / Hint / when xml 'unitHint' exists => Ok
Unit / Hint / when xml 'unitHint' missing i.e. takes default unit => Ok
Unit / Curated drop down => Ok
State Description Pattern => Ok
B. Edit Already Created Item (for Channel)
Type => Ok
Dimension => Ok
Unit => Accepts only manual input. i.e. neither prior value, unitHint, default unit, nor drop down
State Description Pattern => Accepts only manual input i.e. no prior value
2. Thoughts Re: "Unit Builder"
@mherwege personally I think your four level functionality (unit hint + default unit + curated dropdown + manual entry) is fully sufficient (so long as it is also applied when editing an already created item). I also support your wish not to (try to) devise a "unit builder". I also think that a filter-as-you-type would be incredibly difficult to implement.
=> I suggest to start with the current four level functionality (which is already a three level improvement versus the current approach). And if someone wishes it, they can open a future Issue for an eventual further refinement, in a second step.
the intent was to present the actual input control,
Yes and that intent was clear to me but it's tripped up some users. I only brought it up here to make sure we take that into consideration for units.
If you want your energy measurement in Wh or kWh you should just have to type "Wh" or "kWh" into a textbox and be done with it without dealing with a "unit builder" UI.
That was part of the idea from the start. No matter how this gets implemented the user needs to be able to just type in what they want and they have to be able to type in units not already known. The UoM capability allows one to combine units in cool and interesting ways that cannot always be anticipated but OH should support.
@mherwege / @jimtng for info: please note that the two PRs #2312 and #2326 are working on some of the same forms, and probably the overlap is more than can easily resolved via a regular Git merge
@andrewfg The issues you discovered should have been fixed now.
I also slightly changed the autocomplete list: as long as what you type has a match with the curated unit list (including unitHint), show those matching units. When not, show the matching units from the full list.
@mherwege I did some tests. Generally it looks great. Many thanks! However I did find a couple of errors..
Create Mode: On clean build system start-up, initially the Unit and State Description Pattern fields are read only (i.e. they cannot be edited). Editing the Name, Label, Type or Dimension field does NOT change the fields to become editable. However editing the Category field DOES make the fields become editable. Also using the 'tab' character to move to the Unit field DOES make it become editable. Once the form has become editable, it remains editable even when creating yet another new Item. (i.e. I get the feeling that you probably only experience this issue once, on the first time the form is shown, on a clean new OH installation..)
Create / Edit Mode: the Unit field always accepts a manually typed a unit that is incompatible with the selected dimension => I wonder if it is possible to indicate such a mismatch by (say) changing the text color of the unit?
2. I wonder if it is possible to indicate such a mismatch by (say) changing the text color of the unit?
Even the full autosuggest list may not be exhaustive. Giving something that is not in the full list another color is probably possible, but it is not always an error. I don’t have a mechanism to validate a unit is valid.
Create Mode: On clean build system start-up, initially the Unit and State Description Pattern fields are read only
I need to see if I can reproduce this in a development environment. I have little time at the moment, so may take a few days.
@andrewfg This should be ready for a test again.
Apart from the tests you listed, you should also test the same for Group items with base item Number with or without dimensions and units.
@florian-h05 I believe this is ready for review again.
On initial start up in a clean built and clean installed version of OH -- in the Chrome browser -- the Unit field is READ ONLY. However in Edge browser the unit field can be edited. And once an item has been created, the Unit field can once more be edited.
If you start to type something, then the drop down selection does show the typed text in bold (e.g. 'pp'). However if you change your mind and click on something else (e.g. '%') then the newly clicked value '%' does not overwrite the already typed value 'pp'. => You have to backspace to delete the already types 'pp' before you can select a new element from the dropdown.
Once the dropdown has been dropped down, it is impossible to close it. Pressing neither 'tab' nor 'return' has any effect..
Unfortunately because of the above item 3. I could not test anything else..
relativeci[bot]
commented
3 months ago 
andrewfg
mherwege
jimtng
rkoshak
ghys
florian-h05
Closes https://github.com/openhab/openhab-core/issues/4082
This PR adds:
By default, the system default unit (for the configured measurement system) will be shown when editing or creating an item.
units.jscontains a number of frequently used units by dimension and measurement system. These will be available in a autosuggest dropdown list. It is still possible to not select from the list and use any other string as a unit.units.jsnow only contains a relatively small list, but can easily be extended with other frequently used units. All units for the dimension inunits.jswill be in the dropdown list, but they will be sorted by measurement system. If the measurement system is set to US, imperial units will appear higher in the list. Units that have not explicitely been listed as SI or US will always appear higher. When typing a unit that is not in the curated list, a longer list will be used for autocompletion that considers allowed prefixes to base units and constructs all combinations.units.jsalso contains a field to set a different default unit on item creation than the system default unit.With https://github.com/openhab/openhab-core/pull/4079, the REST API of channel types would provide a unit hint if defined in the binding channel types.
If such information is available, this PR adds support for this in the UI. When creating an item from a thing channel, it will suggest to use the unit from the unit hint if available. If not available, it will suggest the webui defined default from
units.js, if not available, the system default unit for the dimension.For dimensions with different units in SI or US measurement systems, it is possible to provide 2 units separated by comma in binding channel types. The first one will be SI, the second US. The suggested one will depend on the measurement system setting.
See also: