Now that I think about it and really look at it, seeing each member’s current state is probably worth having these two pages appear differently.
That’s merged since a week or two now and works fine so far.
As long as you find a reliable way to determine which page you are on, it can show different docs.
Currently it is based on determining the current page path, which should work for Item edit as well.
The next step is to create a markdown doc file in the appropiate directory and following the conventions, see openhab-docs/mainui/CONTRIBUTING.md at main · openhab/openhab-docs · GitHub.
For the documentation of the individual fields, IMO field descriptions or the question marks for each field should be used.
1 Like
Please please…. Please! also change:
“Name” → “Item ID (unique)”
I have always found very very very confusing finding Name and Label together on the UI when the Name is in fact the way you identify an Item and not “friendly” name it (I.e. label it).
Just for comparison Home assistant does just like this for the Entity concept which is equivalent to our Item:
This should also be made consistent and it would be much better to find in the UI: Group ID, Item ID, Thing ID etc
ID rings the bell to any end user that this field is an IDentifier that is unique and cannot be changed.
Name is confusing and too much similar to label.
1 Like
@rlkoshak wdyt? My initial reaction would be no, but maybe we all could get used to “Item ID”.
Either way, this is easy enough to do even in a separate pr.
I don’t want the nomenclature change be the reason to hold up the whole PR.
this
Perhaps a compromise is to call it
“Name (Item ID)”
That is already an improvement, at least the ID concept is in…
Just to show how an unfortunate and confusing choice Name is from a UX pov, BOTH Alexa and Google Home use exactly Name instead of Label to well… name 
devices, for example Google Home:
Anyway this is a i18n-translation change (should be implemented in other translations as well, right?).
Since the difference from Name (ID) from Label is important to beginners, I would strongly suggest to add a line under of explanation citing the ID concept , for example;
Name (Item ID)
The unique ID for this Item
This tells me that Name is actually consistent and is the correct term when it comes to Alexa and Google?
AFAIK this isn’t currently translated. It’s a hard coded text in the UI.
In fact is the opposite!
OH labels and not names/IDs are used by Alexa/GoogleHome integrations by default to be used as Names in their apps.
So what in OH is a Label ends up being a Name in Alexa and Google. But in OH Name is another field: very very confusing.
The concept I want to stress is that Name for the average user is they way you give user friendly names to things, and not internally identify them.
1 Like
OK I misunderstood your original post. So “Name” in Google is the “Label” in openHAB.
I haven’t paid closer attention but IIRC, the openhab “Name” (i.e. Item UID) is also shown in Google somewhere and in fact it’s what it is using internally as the unique id, and not “Label”.
In any case, Changing openhab’s to Name (Item ID) still won’t fix that though, would it?
If I understand it correctly, in Google / Alexa world, Name = Label, they are one and the same, and “Item Identifier / Unique ID” is not the same as Name.
So if we throw in Name = Item ID on the openhab side, that would add to the confusion, don’t you think?
So indeed your original suggestion to change Name to Item ID, or to be consistent across openhab, Item Identifier. Thisis because
In the UI:
- Thing:
Identifier(This should also be renamed toThing Identifierfor consistency) - Channel:
Channel Identifier(When adding Channel)Channel UID(When editing/viewing the channel)
- Create a layout page:
ID
Thing:
Adding a channel
Viewing / Editing a channel
Create a layout (Page)
Yes it’s a bit all over the place
I think I prefer this naming applied to everything
- Thing ID
- Channel ID
- Page ID
- Item ID
- any other ID
because Identifier is a bit cumbersome whereas ID just rolls off the tongue.
OK I’ll create a PR for this at some point.
1 Like
Yes I think referring only to IDs and removing Names everywhere is the final goal.
Name is too similar to Label and really confuses.
As a intermediate step also maybe you could take into account my suggestion of having:
Name (Item ID)
The unique IDentifier for this Item <— explanation text beflow the field
The problem is that internally inside openhab core, Item Name is what it is generally known as.
@Override
public String getUID() {
return getName();
}
@Override
public String getName() {
return name;
}
Yes I know, as I am myself a binding developer.
But in Java you have another layer:
UID > Name > Label
while the user sees only:
ItemID (currently Name) > Label
I do not think the general basic user cares much about OH internal core, he does not even know what that is.
You are designing the UI for everyday users , not for developers!
Much better to ask an attribute translation in the mind of developers, than to confuse all final users that just want to Name/Label things.
1 Like
Just created a new issue to track this:
If in the end you have the ID in the field I think the line explanation below is not needed.
Also ID is more than enough, UID is again very much familiar to a developer than an average user.
In general to get more info for attributes in the edit page it would be nice to have a (?) tooltip or button that links to the documentation page
IMO the most essential information about each field to set up should be provided in the fields description, but of course we should link to the docs.
This page is what is currently shown in the sidebar help when a Item or the Items list page is opened: Settings - Items | openHAB
It links to the concepts page, which I checked, and the concepts page is not explaining Name vs Label. Probably the concepts page should be extended with that. Though the Items config page explains that: Items | openHAB
Unrelated to the current topic, I’ve always been confused because there are multiple places in the docs about “Items”, “Things” (one in Concept, and another in Configuration). I’m slowly coming to terms with it, but it is still confusing to me.
I’d rather see ONE single page for the source of information when I need to know about “Items” rather than wondering… “is that information in the Concepts, or in the Configuration section?”
I’d end up going to one, then to the other one to find what I was looking for.
It makes our doc structure overwhelming.
4 Likes