How to take advantage of item metadata widget configuration

I do not get the meaning of defining the widgets in the item metadata. Let’s take this as example:

String                  DebugItem               "A item to debug [%s]"                               <water>                    {widget="oh-card"[icon="oh:water"],listWidget="oh-label-item"[icon="oh:water"], cellWidget="oh-label-cell" [icon="oh:water"],title="My Water"}

with this we get the following:

Let’s say I want to edit the list item widget and set an icon.

If I add this item to a list card as label list item like this:

                    - component: oh-list-card
                      config: {}
                          - component: oh-label-item
                              item: DebugItem

The icon is not shown. My expectation was: every time this item is used in a list it is rendered as specified in the item metadata.
So how to use this in a widget? Or more generally: how does it correspond to the widget yaml?

Your expectation is not quite what is going on. The default widget metadata is only for specifying the name of the widget that the item uses in either a standalone or list context. There is no further configuration available through that particular metadata namespace.

When calling a widget it is not possible to send just any information to it, the widget’s only a small set or parameters that can be passed in during widget creation. All the widget metadata does is call the specified widget and if that widget has a parameter that is defined as an item it passes the name of the item to the widget.

If you want the widget fully customized you’ll have to build it yourself in the editor.

People are using parameters for the widgets though (e.g. [OH3] Add metadata to Items via configuration files).

Can someone please show a good example when and how to use this? Or explain the concept?

Apologies, I misunderstood your initial question. The actual answer is:

The “default” widgets for an item are not the widgets or widget settings that are used anytime this item is used anywhere; they are only the widgets that are used if the item is included in one of the UI autogenerated contexts.

So the Default Standalone Widget for an item is, for example, used in it’s item details page, but not if you just try to include that item in a custom page or widget. The default list item is used whenever that item appears in a group list or (if it’s part of your semantic model) in one of the cards on the locations, equipment, or properties tabs, but not if you are building a custom list as part of a widget.

If you are really going to use one particular configuration in many different custom pages and widgets, you can create an individual custom widget that includes all the configuration you want to be standard and a configurable item parameter (plus parameters for whatever else you might want to be able to configure) and then use that custom widget in other yaml definitions like this:

- component: widget:name_of_custom_widget
    item: SomeItemName

As I said in my previous (somewhat confused) response, however, if you are going to do this, any thing you want to be able to control about this widget you are including needs to be defined as a parameter, you would not have access to the config space of the components in name_of_custom_widget from the calling widget or page.

1 Like

In a related, but slightly different context … is it possible to refer to previously defined item metadata with a widget … say display a metadata configuration in a widget, like so:

Switch Dishwasher_AutoResumeOK "Allow Auto Resume" (Dishwasher_Setting,Appliance_Setting, Dishwasher_Setting_es) ["Switch", "AutoResume", "Toggle"] {widgetOrder="34", listWidget="oh-toggle-item" [footer="=items.metadata.getMetadata(items['Dishwasher'], 'characteristics').configuration.autoResume"]}

The above item is supposed to display (or exploit …) the metadata setting in the widget itself. It doesn’t work and returns ‘undefined’ as a footer…

while the same expression in a (test) rule’s script

console.log(items.metadata.getMetadata(items['Dishwasher'], 'characteristics').configuration.autoResume);

returns the correct output:

2023-04-27 11:32:56.884 [INFO ] [g.openhab.automation.script.ui._test] - true

It is important not to confuse what possible within the various rule scripting languages and what’s possible in custom widgets. JSScripting is a full js implementation with an extensive OH specific helper library. The expressions you can use in widgets are defined by a limited js-like parser, meaning they use the same syntax and several standard js libraries but it is not and never really can be a full js implementation.

Yes, but only under one particular condition. When an item is returned as a result of one of the item list options in an oh-repeater (e.g., itemsIngroup) then you can also specify one or more metadata namespaces to return as part of that item object. I suspect if you search the forum for fetchMetadata you will get a few hundred examples of how this works.

Justin, thanks, I had seen these examples (and particularly the one, where you are editing metadata using a rule. The usecase here is much simpler; Just display (or use as a condition) a metadata value of the same or another item. The examples really seem a bit of overkill for a plain and simple toggle-listWidget… where I would then - instead of reconfiguring - say a footer or a subtitle or hide an item - create a full new widget, where the oh-repeater item isn’t really of any use, when I just want to deal with one item.

I hear you. Unfortunately, the fact remains, that is currently the only way to access metadata information in a widget.

It all comes down to limiting the amount of unnecessary information that crosses between the core and the UI. MainUI (as with all the other UIs) gets its information with calls to the core API. In order for the UI to be as fast and responsive as possible it can’t be collecting more information than it needs. 99 times out of 100 widgets don’t need any metadata information.

As an example important data saving, one of the most widely used metadata namespaces, stateDescription isn’t even passed directly to the widget contexts, but processed prior to that so only items with modified states have that information included in the widget context.

There’s been a recent change in how calls to the metadata are handled because these days there doesn’t appear to be too large a performance impact with additional metadata returns, but it is still necessary to limit that info on a widget by widget basis because even a single MainUI page with a handful of widgets makes probably dozens of API calls and too many API calls with all that metadata info would be a noticeable drag on performance.

1 Like