I’m taking a cut at expanding the Getting Started tutorial for Pages. I’m going to insert them here for public comment before submitting them as a PR. I don’t think the existing three pages are sufficient for getting started so I’m largely rewriting them but will leave them inline at the end until I’m certain that all their contents are covered elsewhere.
As usually, this is a Wiki (for now) so please correct anything wrong and add any content you think is missing and add a reply describing what you changed. I’ll convert it back to a regular post and close it once it has been migrated to github.
This page has moved to the docs. Please see the open PR at Getting started UI Pages by rkoshak · Pull Request #1503 · openhab/openhab-docs · GitHub and a preview at Pages - Custom Widgets | v3 Documentation Preview.
Under Developer Tools there is a “Widgets” option. From this menu there is a tool to develop custom widgets. These are “generic” widgets that allow you to define and set a property to, for example, identify the Items that will populate the widget. Custom widgets are great for:
- building a complicated widget to share with other openHAB users
- building a complicated widget that will be reused across multiple similar devices in your home automation (e.g. a player widget for all your chromecasts)
- building a simple widget that will be reused across multiple similar devices (e.g. configure how you want all your light switches to look and work once and reuse it across all of your light switches.
This tutorial is not going to be a complete tutorial for building widgets. That topic is too large for a getting started tutorial. Instead, it will demonstrate a couple of simple use cases to give a taste of what is possible.
Simple Example
This example will show how to create and reuse a list widget for all your light switches. Once created, the custom widget will appear in the list of options for the default list widget where it can be selected and configured for that specific light switch.
Create the Widget
First navigate to the Developer Tools and select Widgets.
Click the + icon.
You will be presented with a split screen view of your widget code and a live preview of how the widget looks. It will be prepopulated with a number of fields.
uid: widget_5c7a60b74f
props:
parameterGroups: []
parameters:
- name: prop1
label: Prop 1
type: TEXT
description: A text prop
- name: item
label: Item
type: TEXT
context: item
description: An item to control
tags: []
component: f7-card
config:
title: '=(props.item) ? "State of " + props.item : "Set props to test!"'
footer: =props.prop1
content: =items[props.item].displayState || items[props.item].state
| Element | Purpose |
|---|---|
| uid | Unique identifier for the widget. I recommend replacing this with a meaningful name. |
| props | A place to define properties that will be used by the widget. The props are referenced by name through an expression using the props Object. If you create a new widget, you will start with an examplenatory YAML that shows how props are define (segment props:) and referenced(segment config:). You start with 2 text props (prop1 and item) and referenced as (props.prop1 and props.item). When selecting the widget for use, a configuration form will be presented to allow users to define the props. |
| tags | A way to add a little extra info to a widget to describe what it is and what it’s for. |
| components | This is where the actual widget starts to be defined. |
| config | This is the configuration for the widget. |
Now that we have an idea of what all these fields are for, let’s create a list widget to use for all our light switches.
Unfortunately, the widget builder does not have a form to easily create a widget. So I recommend opening another tab and creating the widget the way described in the previous page of this tutorial. Make sure to select the card type instead of accepting the default and to select the Item so that all the fields are present in the code tab.
value: oh-toggle-item
config:
icon: f7:lightbulb
iconColor: '=(items.FrontPorchLight.state == "ON") ? "yellow" : "gray"'
color: '=(items.FrontPorchLight.state == "ON") ? "yellow" : "gray"'
title: Front Porch Light
item: FrontPorchLight
We will use this YAML information to build our custom widget.
I’ll set the uid to “light_list_widget”
To better identify it I’ll add “list” and “light” to the tags.
Looking at our YAML from the widget we defined above we see that the component type is oh-toggle-item.
Copy everything under config from the widget already created and paste it under config in the widget builder.
Note, apparently this type of component is not renderable in the preview.
Next we want to set the properties. In this case we want to be able to customize the title and the Item that is used. So we define a property for each.
Finally we need to update the configuration to use the props and save.
The resultant YAML is:
uid: light_list_widget
tags:
- list
- light
props:
parameters:
- description: The label for the widget
label: Title
name: title
required: false
type: TEXT
- context: item
description: The light switch Item
label: Item
name: item
required: false
type: TEXT
parameterGroups: []
timestamp: Jan 28, 2021, 4:27:14 PM
component: oh-toggle-item
config:
icon: f7:lightbulb
iconColor: '=(items[props.item].state == "ON") ? "yellow" : "gray"'
color: '=(items[props.item].state == "ON") ? "yellow" : "gray"'
title: '=props.title'
item: '=props.item'
Now return to the model and select a light switch Item and add a Default List Item Widget. Select the Widget type and this time select your newly created widget from the bottom of the list. You might need to refresh the page if it doesn’t show up.
You will see that the form changed to ask for the properties you defined. And because we gave the Item context field (see the yaml above) MainUI was smart enough to select the current Item for you. However I found that I had to reselect it to get the toggle to render correctly.
Verify that the widget rendered as expected. If not you may need to update or fix a problem (sometimes a refresh of the page is needed for the preview to show the correct state).
value: widget:light_list_widget
config:
title: Family Room Lamp 2
item: PeanutPlug4_Switch
Now that you have a working widget, you can reuse it for all of your light instead of needing to repeat the same setting changes over and over again. But an even bigger advantage is that when you update the widget under Developer Tools, all the Items that use it will instantly update too. So you can change how all the Items that use this widget are rendered in one place.
This will save you a ton of effort when customizing how your Items appear in the automatically generated cards.
TODO: Add creating a stand alone card (chromecast widget)
TODO: Create a card for text and date time input
TODO: Create an accordion list example
Next → Building Pages in the OH3 UI: documentation draft (2/3) (replace this with the next page in the tutorial)
Previous ← Building Pages in OH 3 - Item Customization on Auto Generated Pages
Next → Rules - Simple
Previous ← Pages - Item Widgets
