UPDATE: The most current information on this topic is now available at: User Interface Design Overview | openHAB. The following is kept for archival purposes only!
TOC:
I. Pages basics (this topic)
- Concepts: UI components, pages & widgets
- Sitemaps
- Types of pages
- Page editors, creating a page & adding widgets
II. Editing pages & widgets: general information
- Configuring widgets
- The system & standard libraries, default widgets (standalone, list items & cells), adding widgets from the model
- Widget actions
- Expressions
- Personal widgets: development & usage
III. Building specific types of pages
- Layout pages
- Floor plans & maps
- Chart pages
- Tabbed pages
Concepts: UI components, pages & widgets
In openHAB 3 Pages there is a concept of âUI componentsâ. UI Components can be created using the UI and they can be viewed and edited in YAML from the Code tab. There are a number of component types for showing information and interacting with your Items including toggles, knobs, sliders, text entry, date and time pickers, etc. These components can often be combined to form a composite component for advanced displays (e.g. a weather widget showing current conditions and the forecast and access to your thermostat settings).
UI Components are presented on Pages. There are a number of different Page types.
Types of Pages
- Layout pages: Allows you to organize/layout multiple widgets on the same page in many ways. The below screenshot shows only some of the different types of UI components that are available.
- Floor plans & maps: Allows you to put markers over the top of a background layer that you can zoom & pan. You can use your own picture (like the example showing a floor plan), or a map of the world;
- Chart pages: A page based on the powerful Apache ECharts to visualize historical data:
- Tabbed Pages: Use to group several pages that are selectable between them with tabs on the bottom:
Construction of a UI Component
As mentioned, a UI Component can be inserted and configured through the Page builder interface (Settings â Pages). For advanced configuration, sharing with others, and advanced configuration a YAML representation of the component can be viewed in the Code tab of the UI Component editor.
For example:
component: oh-type
config:
prop1: value1
prop2: value2
prop3: =expression
...
slots:
default:
- component: ...
config: ...
slots: ...
- component: ...
anotherSlot:
- component: ...
...
...
This is a little bit technical but youâll encounter these YAML structures pretty often when you start doing advanced things, as the various editors in the UI have menus everywhere to edit the YAML of a component directly.
Each component has a type, configuration properties which can be made dynamic with expressions (not always though, more on that later), and optional slots which hold more components. Slots are optional, and have a name; usually when thereâs slots involved thereâs a default slot but itâs not guaranteed. The semantics of both the config properties and the slots depend on the component type, as well as the allowed sub-component types in the slots.
At the top of the tree thereâs a root component which has additional attributes:
uid: component1
props:
parameterGroups:
- name: group1
label: Property group
...
parameters:
- name: prop1
label: Prop 1
type: BOOLEAN
groupName: group1
description: What prop1 does
- name: prop2
label: Prop 2
type: TEXT
context: item
description: Choose an item for this prop
- name: prop3
type: NUMBER
advanced: true
...
tags: ["tag1", "tag2"]
component: ...
config: ...
slots: ...
The root component has an uid (itâs Unique IDentifier), a props structure describing its own properties (when we reuse a component in another one, for instance a personal widget on a page, this will help in building a user-friendly configuration sheet to set up the widget; the props parameters and descriptions adopt the structure of the configuration descriptions found in bindings, services and throughout openHAB:
https://next.openhab.org/docs/developer/bindings/config-xml.html
[ RLK I propose striking the following paragraph and reintroduce it later when/if itâs needed. A new user (or even myself) doesnât know what any of this means or why I need to know it. ]
Root components are stored in namespaces; for instance, the pages are stored in the ui:page namespace, the personal widgets in ui:widget, HABPanel uses UI components to store its panel configurations and dashboards, and UI-managed sitemaps are stored in the system:sitemap namespace. The component types valid in a specific namespace vary.
Sitemaps
Sitemaps are an efficient way of organizing and displaying Items. There are many dedicated clients able to render them: Basic UI, the mobile apps, the Windows app, Pebble and others.
Unfortunately, the main UI, cannot render them. However, it can store âmanagedâ sitemaps and if properly formatted, they will appear in clients as uicomponents_{uid}. Note that this doesnât prevent writing them in files with the dedicated syntax - they simply wonât be listed in the main UI or be editable through the UI.
Page editors, creating a page and adding widgets
To manage pages, first login as an admin, then from the sidebar, under Administration in the sidebar, go to Settings then Pages. The list of pages (and managed sitemaps) will appear. You can group name alphabetically or by type. Click on a page in the list to edit it or use the â+â button in the lower-right corner and choose the type of page you wish to create:
Note that you likely already have a page named âOverviewâ (uid: overview) represented by a home icon. This page is a special one, itâs created by default and it cannot be removed. The contents of this page will be displayed on the Overview tab of the home page. This overview page includes several tabs which will display Items that are part of your semantic model in various ways including:
- location
- equipment
- property type
To delete pages, use the Select link in the upper-right corner and check the pages that you want to delete, then click the Delete button (the appearance will differ depending on the current theme).
The look & feel of the page editor will be quite different depending on the type of page thatâs being edited, but they will feature more or less the same elements (except the sitemap editor).
The Design and Code tabs allow to switch from a visual editor to a YAML representation of the page
If youâre on a desktop, you can use Ctrl-S (or Cmd-S on Macs) to save the page quicker. Currently, youâll be taken back to the pages list when you save with Ctrl-S if itâs never been saved before (i.e. youâre creating it), afterwards you will stay in the editor. When you click/tap on the Save button, however, you will always go back. Also, if you create, update or delete a page, the change is only detected detected in the current instance of the UI, on the other ones youâll have to refresh the page with browser to reload (if you donât have a refresh button go to Help & About and click on Reload the app).
In the Design tab, youâll find a header with some general settings about the page:
- its UID (that can can only set once, during the page creation, after that you cannot change it);
- the label;
- an additional collapsible section with:
- âvisible only toâ: allows to select the user role(s) you want the page to be visible to; if none are specified the page is visible to unauthenticated visitors as well;
- âShow on sidebarâ : allows to control whether or not the page appears in the sidebar menu on the left - indeed, itâs not necessary to display all pages in it; using widget actions (see below), you can display other pages (standard navigation or in modals like popups etc.), thus creating hierarchies of pages is possible, the sidebar menu being the entry pages to these hierarchies. You may also choose to hide pages from view until theyâre ready.
- âSidebar orderâ: allows to reorder the sidebar menu, choose an integer for each page on the sidebar, the lower values will make the page higher in the menu.
Do not be fooled into assuming the âvisible only toâ feature gives you any security, itâs only a way to restrict the visibility; it can be enough for non tech-savvy users but there are many ways to circumvent this restriction and talk to your items anyways.
Some editors also feature a âRun modeâ switch in the bottom toolbar:
With this switch you can preview how the page would look when viewed outside the editor, to go back & forth quickly between the design interface (or code view) and the run mode, you can also use Ctrl-R on a desktop (Cmd-R on Macs).
Now that we have a basic understanding of what Pages are and how to manage them, letâs see how to build one step-by-step.
