Trying to understand Getting Started: Custom Default Item Widgets and totally confused

Hi, I’m trying to follow Pages - Item Widgets | openHAB but find it very confusing.

The first thing I’m trying to understand is what a Widget is and if this is something I want to use. Is there any other part explaining this I missed?

I start by reading the first sentence of the tutorial:
“As with the Overview Page and individual cards, the way individual Point Items are presented can be customized.”

Ok, I know what the Overview Page is and remember it well from not looking like shown in the tutorial from the start. There were some cards, but I don’t know which are the individual cards and which not.
There were Point Items in the semantic model. I found they have additional tags called Property discribing their sort of point. But I can’t find a definition of a Point Item.

And my last question about this sentence: How is this connected to Widgets?

  • Platform information:
    • Hardware: CPUArchitecture/RAM/storage
    • OS: what OS is used and which version
    • Java Runtime Environment: which java platform is used and what version
    • openHAB version: 3.3.0
  • Issue of the topic: please be detailed explaining your issue
  • Please post configurations (if applicable):
    • Items configuration related to the issue
    • Sitemap configuration related to the issue
    • Rules code related to the issue
    • Services configuration related to the issue
  • If logs where generated please post these here using code fences:

Welcome to the forums, I think we can get you on the right track.

You have, in fact, stumbled upon the definition of Point Item but it is so much less dramatic than expected, that you didn’t recognize it. A semantic point is not a specific type of item; a semantic point is nothing more than any item of any basic type that has one of the semantic point tags.

This is the fundamental construction of the entire semantic model. An item is part of the model (location, equipment, or point) if it has a tag identifying it as such. Semantic and non-semantic items function in exactly the same ways in all respects with the one exception that semantic items have that one little piece of additional information that allows the UI to do some automatic organization and display. You don’t even have to make use of the semantic model if you don’t think those few extra features will be of use to you. Some users find those extra features very valuable and some do not.

The MainUI (the default UI for administration that you are already using with OH3) shows pages. When it first loads, it shows you the overview page by default, you can create other pages and link to those pages in various ways. Blank pages, however, are no fun.

A widget is just a graphical element on a page that MainUI uses for interaction and/or display of information (usually derived from item states). Do you want a switch that turns a light on and off? Then you need a widget that includes a toggle on it. Do you want to see a list whether all your windows are open or closed? Then you need a list widget connected to the information from your window sensors.

A widget can be as simple as control of a single item and as complex as you’d like to make it (there’s an active project right now building an entirely new theme/UX for the MainUI using custom made widgets).

An item’s Default Widgets sit at the intersection between these two ideas. Because use of the semantic model allows the MainUI to build some automatic pages of information. The UI has to know what widget to put on those pages for each type of item. There are two types of default widgets for each item: standalone, and list.

If you have created an item and you navigate to SettingsItems and select that item from the list, then you will be taken to that item’s details page. It looks like this for a switch item:

That big switch at the top of the page that you can click on to turn the light on and off, that is this item’s default standalone widget (in this case that widget is a oh-toggle-card). A default standalone widget is the widget the UI will choose to display an item directly on a page.

If you have set up any part of the semantic model, then, then you can click on the tabs at the bottom of the overview page (equipment, locations, or properties) and see the auto-generated semantic cards (it’s the exact same information in all three cases, just organized in different ways). If I open up my equipment tab and select the Power Outlets card, then I see a list of all the items I have tagged in my semantic model as points of PowerOutlet equipment:

For the garage outlet and the lamp, these are the only points of those particular outlet equipment groups so they are just shown in the list with toggle controls. These are the default list widgets for these items; the widgets that the UI will choose by default for display of information in a list.

My wife’s seedling grow table list item looks a little different. That’s the actual equipment group because there is more than one point. Here’s the model definition:

I have set the option in the equipment page that collects the points of a single equipment in this so called accordion list so it doesn’t show a toggle but instead has an indicator that you can click on that list item to expand more information. It looks like this:
and once it is expanded it is still showing the default list item widgets of those points.

Once you get used to the widget system you can create your own (or install others’ custom widgets from the marketplace) and put them on any page you want in just about any way you want. However for users who like the semantic model, but want some of the their items to display differently than the built-in default widgets, there is also a setting for each individual item to define a custom widget that the UI will use for display. The page you have linked to starts with a discussion of how to make those specific changes and get different default displays of items.

1 Like

Thank you for your answer.

Did I get it right that:
Point Item == Semantic Point ?

I have already built a (semantic?) Model consisting the house with floors with rooms with equipments created from things.

I have a lot of Items (Button, Color Temperature, Battery Level, Brightness) belonging to different things. Some have a “Point” as class in Semantic Classification. Are those the Point Items?

Is a Widget connected to one or more Point Items? Like it has some Point Items as parameters and can control Point Items?

On my Overview page I have a card (= Widget) which uses the open/close state (= Point Item) of a window sensor (=Thing) as a parameter to determine it’s Background color.

Yes, it’s an Item with one of the Point semantic tags.

Yes, “Point” is the default Point tag. But there are others like “Alarm” and “Status”.

It can be. Or it can be connected to one Item or no Items. Widgets can also interact with Items that are not Point Items or even Items that are not in the semantic model at all. Some widgets might not be use any Items at all. But that’s not what that page in the Getting Started Tutorial is about. See the page following that page for that stuff: Pages - Custom Widgets | openHAB

That sentence in the Getting Started Tutorial is referring back to the previous page which talked about the Overview Page. As discussed on that page, three of the four tabs that make up the Overview page are automatically generated based on your semantic model. A key sentence from that page in the tutorial:

Clicking on the card will bring up a list showing all the Equipment and Properties at that location. Equipment is represented as a gray bar with the name of the Equipment, and each Point/Property is shown with its default list widget.

The page you linked to is the next step. The previous page talked about how to configure the overall overview page and tabs. This page discusses how to customize the widgets used by the Overview tabs for individual Items. Since only the Point Items are represented with a Widget on those tabs, we are precise and indicate we are talking about the Point Items.

While you can apply a “default list Item widget” to Items that do not have a Point tag, there isn’t much benefit to doing so. For the most part, that widget is only used by the Overview tabs.

But that section of that page is only referring to that, not widgets in general.

For some examples, here’s a custom widget for my garage that involves a camera feed and five Items (only two of which are part of the semantic model and therefore are Point Items).

Here’s a location card. Everything you see here is part of the semantic model since that’s all that gets shown on the Location tab. The Location is “Front Room”. The Equipment is represented by a gray line with a label (e.g. “Front Door”). All of the point Items in that equipment are shown below that with what ever is configured as that Item’s “default list item widget”.

OH makes it’s best guess as to what the default widget should be but if you want to customize it you need to change the “default list Item widget” metadata for that Item.

If you have more than one of that type of Item, you should create one custom widget (under developer tools) and apply that to each of that type of Item’s metadata.

Here too you can have one widget that represents more than one Item e.g. that Front Door widget can be clicked on to unlock the door’s deadbolt and the badge on the right shows whether the door is open or closed. But if you do that, one of those Items (the Switch to open the lock or the Contact showing the status of the door) should either not be part of the Semantic Model, or it’s “default list item widget” metadata should have visibility set to false.