[wiki] Building Pages in the OH3 UI: documentation draft (1/3)

Tags: #<Tag:0x00007faf9aa038f8> #<Tag:0x00007faf9aa03768>

As this new concept of pages is getting fairly complex but the feature set is stabilizing, I thought it might be about time to start drafting the documention for it so that a good enough iteration could make its way to the docs before the OH3 release. I also planned to talk about them briefly in the [wiki] Getting Started with OH3: rewriting the tutorial - 1. Introduction tutorial rewrite, but this is more of a deep-dive. As always this is going to be a wiki so if you feel like correcting spelling mistakes or the language, or rewrite some parts, feel free to click on that edit button!


I. Pages basics (this topic)

  1. Concepts: UI components, pages & widgets
  2. Sitemaps
  3. Types of pages
  4. Page editors, creating a page & adding widgets

II. Editing pages & widgets: general information

  1. Configuring widgets
  2. The system & standard libraries, default widgets (standalone, list items & cells), adding widgets from the model
  3. Widget actions
  4. Expressions
  5. Personal widgets: development & usage

III. Building specific types of pages

  1. Layout pages
  2. Floor plans & maps
  3. Chart pages
  4. Tabbed pages

1. Concepts: UI components, pages & widgets

In OH3 there is a concept of “UI components”. UI components are stored in the JSON DB and managed with the REST API. The structure of a component can be represented in YAML as follows:

component: oh-type
  prop1: value1
  prop2: value2
  prop3: =expression
    - component: ...
      config: ...
      slots: ...
    - component: ...
    - 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 may be eventually 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
    - name: group1
      label: Property group
   - 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 technical 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 building an user-friendly configuration sheet to set up the widget; the props descriptions adopt the structure of the configuration descriptions found in bindings, services and everywhere though openHAB:

Root components are stored in namespaces; for instance, the pages are stored in the ui:page namespace, the personal widgets in ui:widget, HABPanel now uses (will use :smirk:) 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.

[RLK question: Is it appropriate to insert a comprehensive example here? I’m not sure I was able to glean enough to go off and put this all together]

2. Sitemaps

Sitemaps are an effecient 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 (yet?). However, it can store “managed” sitemaps in the system:sitemap UI component namespace 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 [add link to sitemaps docs] - they simply won’t be listed in the main UI or be editable when you don’t have access to the file [RLK provide more detail, what does it mean to not have access to the file, do you mean to say that they can only be seen or edited from the .sitemap file itself?].

3. Types of pages

The main UI has merged the managed sitemaps in a concept of Pages, which also includes other types that only it can render at this stage. The types of pages are:

  • Layout pages: allows to organize widgets on the page in many ways, not unlike HABPanel’s dashboards;

  • Floor plans & maps: Allows to put markers on a background layer that you zoom & pan, either your own picture (of a floor plan or anything, really), or a map of the world;

  • Chart pages: A page leveraging the powerful Apache ECharts to visualize historical data:

  • Tabbed pages: allows to group several pages in one and switch between them with tabs on the bottom:

4. 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 the setup wizard and it cannot be removed. The contents of this page will be displayed on the Overview tab of the home page.

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).


I’m making a few changes. Feel free to reverse any of them.

I think we should avoid too much comparison of OH 3 to OH 2 in the core documents like these. There will be a growing number of users whose first exposure to OH is going to be through OH 3 and calling back to OH 2 to help explain core concepts may add to their confusion rather than add clarity. I would hope that those who are proficient in OH 2 would recognize when there are similarities or minor differences.

We could also create a migration tutorial again and centralize all those subtle differences in one place that a new user to OH 3 would never look at.

The changes I’ve made above reflect this idea.


By all means, yes! :astonished:
I was just re-reading myself and realized I might have needed an additional coffee or two before writing this thing this morning :wink:

It’s always hardest to write the first draft. It’s a good document. I’ve inserted a couple of notes/comments above inline.

Mainly, I’m not sure how to put it all together in the first section. Maybe a comprehensive example would help showing a UI with a bunch of elements and the YAML that generates it would help.

I’ve a question at the end of section 2 regarding what you meant by “does not have access to the file”. If I understand correctly maybe it would be more clear to write the sentence as

Note that this doesn’t prevent writing them in files with the dedicated syntax [add link to sitemap docs] but any sitemap defined in a .sitemap file will note appear in the main UI and can only be edited through changes to the .sitemap file itself.

1 Like

I understand, as mentioned it’s a overall view of the general concept which is all-important for what’s coming - all this is allowed because of a generic API is now available for UIs to store their stuff, really. And since that component structure will be encountered everywhere when editing page-related things in “code view” I thought it might be valuable to describe it first - maybe at the risk of putting off some users, that could be an issue for sure, I agree.

Yes indeed, in openHAB there are “sitemap providers”, there was the one which provided a thing-oriented “_default” sitemap in OH2; this one has been removed AFAIK, but there’s still the provider parsing .sitemap files and now there’s the “managed” UI components one. The resulting set from all sitemap providers is fed to the clients as one unified set; but a sitemap from one provider can’t be changed by another provider, in other words, you cannot change your file-based sitemaps from the UI, or the other way around (unless you edit the JSON DB).

Will the new UI concept be reflected in the Android app?

Not with native controls, but I’m sure the Android app will be able to show the UI (like it does with HABPanel) eventually. It works good enough as a web app, and you can already add it to the home screen and run it fullscreen.

Hi guys

Its possible to build a widget with subsequent that shows other info like the one I built in habpanel

And furthermore its possible to change the command that rollershutter widget send?
The widget send the command DOWN , I want send command close instead

Thanks in avdance

This seems quite similar to https://framework7.io/vue/accordion.html#examples so with some styling I think this could be possible.

The rollershutter control is little more than segmented buttons but tailored to control a standard Rollershutter item, if you have a different situation it’s likely possible to reproduce its functionality in a custom widget using f7-segmented and f7-button with your specific commands.

Thanks for the answer Yannick Schaus

Other info concerning standard openhab widget,

What string i should insert into icon fileds if i want to use icon in icon/classic folder?

The same for floorplan images, it works if I put an external url, but if I insert localhost/image.png it doesn’t show nothing (standard missing image icon)
What is the url for local file?

And how to show different color for icon based on item values? The example in expression doesn’t work in standard widgets

Thanks again for your support

@livio You should be able to access local icons (…/openhab/icons/classic/) by using the ‘oh-icon’ component with the config parameter ‘icon: YOURICON’.

There is currently no option to change the icon color (for local icons) with styling params like ‘color:’ AFAIK (at least, not for the oh-icon component) - I think it has something to do with the fact that icons gets imported as images and not as a font (like the f7-icons do).
But you could use ‘filter:’ as a style to trick a bit (with good support for the most browsers)

Here is a great Codepen, which should help you, finding the correct filters to apply to set your desired color.

For example, setting your icon color to red (#ff0000):

filter: invert(14%) sepia(99%) saturate(7416%) hue-rotate(0deg) brightness(94%) contrast(114%)

To show/hide the respective icon based on the item state it should be possible to do that with the visible param… e.g.: ‘visible: =items[props.item].state === “OFF”’

To show a local image for e.g. a floorplan use the - its respective folder would be ‘…/openhab/html/floorplan.png’.

Hope it helps.

This Is clear that the new UI does not allow editing an existing sitemap. But does it at least allow rendering such a sitemap so that we can control our home in the new main UI as before without a full redesign?
Of course, we have still the old UIs and this will not not be a full break even if control of existing sitemap not possible in the new main UI could be very deceiving for most of users in a first time.

At least the information should be absolutely clear in the documentation.

I have not found how to control my home with my sitemap in the new UI when I tried OH3.

You can install BasicUI and reuse your existing sitrmap. What is unclear ?

1 Like

If you mean an existing sitemap file, the UIs have never done that. OH assumes if you use files you edit the files yourself with your favorite editor.

Basic UI is there for using sitemaps. The new UI does not use the old sitemaps.

If true, this is exactly the information I would like be mentioned clearly in the documentation.

I assume I will not be the only one to ask myself this question.

1 Like

You mean like this?

Please re-read before posting. It is clearly stated in plain English. I just added emphasis above.

1 Like

The “(yet?)” is very confusing. Does it mean this is not yet finished but it is in the pipeline ?

That means it does not work NOW.

To me “(yet?)” means they have not yet decides whether it will ever work but it may ne a remote possibility.

Either way we are talking here about current behavior and it is clear on that point.