Building Pages in the OH3 UI: documentation draft (2/3)

I am learning from it so it is a good start.

Added to the end of section 8

= ( === '0') ? 'Off' : ( === '1') ? 'Heat' : ( === '11') ? 'Economy Heat' : ( === '15') ? 'Full Power': ( === '31') ? 'Manual' : 'Not Set'

Stacked ternary statements to translate a value to a description.

Expressions can be tested in the Widgets Expression Tester found in the Developer Sidebar

what does




give you in the expression tester?

The oh-plan-marker component seems to not support the visible: property - if you see a usecase for this, it’s worth opening a enhancement suggestion for this on github

Thanks for pointing out the expression tester! I wasn’t aware of it:

Obviously I wouldn’t need a ternary operator in this case, of course.

Thanks for the research Rainer, I would have even known that I am using that type of component.

Yep, the idea is to make items appear and disappear depending on a state or in my case I wanted to make the icon blink in case of an alarm. The only idea I have to make it blink is to switch icon images.

I probably ask for this to be added to the component. :slight_smile:

The way I solved it is by toggling between the “oh:alarm” and and empty one: “oh:none”.

You can change the visibility of an component with classes as well. So if the visibility attribute is not available use the class display-none. See my example:

- component: f7-button
    class: '=(props.propZoneArray) ? "" : "display-none"'

If you need some more examples maybe this one can helb you too. I‘m using this kind of visibility there as well on some components.

1 Like

it seems the oh-plan-marker also doesn’t support the classes attribute. As you can see the alarm-icon is still shown although the expression does compute “display-none” :

Could you please add some examples/templates?
I am interested to see how these widgets are configured:

Thank you!

As a suggestion, which aspects should additionally be covered in a documentation I’ve collected some questions which I came across while trying out OH3:

  1. What’s the purpose of the built-in Overview Page, what/why is it different from other pages?
  2. Description of basic (and obviously mandatory) structure of pages (oh-block, oh-grid-row/cols oh-cells, any others?). Description of the intended design pattern and layout behaviour (when to use what). Description why those widgets are mandatory.
  3. Overview about all built-in OH widgets, their purpose, configuration options and visual demo (similar to F7 docu and kitchen sink)
  4. Explanation of which f7 components can be used and where (e.g. why not use f7-block and f7-grid?). What are the restricions? Can oh- and f7-widgets/components be mixed?
  5. Explanation of YAML structure (config section, what are slots and where can I find information about named slots? What is a default slot and why do some components need them, some not? What does “glance” mean instead of “default”?
  6. Styling: How can styling (margin/padding/colors/shadows) of built-in components (–f7 CSS Variables) be changed?
  7. Styling: recommendation on how to define custom CSS classes and variables to be able to maintain a constistent styling across all built-in and custom widgets
  8. How can custom widgets be nested (e.g. a arbitrary number of custom list-items into a custom list)?
  9. how can I define a flex layout that has several columns on large displays and a single column on an iphone (display width of 375 pixels)?
  10. when I “Add widget from model…” the default widget set in the item settings is used. Which effect does it have on the page design when the default widget setting is changed later on?
  11. how can a user debug the page/widget design (often the preview shows a blank page after code changes)?

Note I’m in the progress of rewriting these Page parts of the tutorial. You can see the work in progress starting at [Wiki] Building Pages in the OH 3 UI - Introduction.

Yannick is also working independently on reference documentation for pages.

The Getting Started Tutorial is not intended to be comprehensive reference documentation. It is only intended to cover, from end to end, the most common stuff a beginner with OH 3 might want to do. Creating a new complicated custom widget is not something that a user of the Getting Started Tutorial is going to need or want to do. That’s a more advanced skill that they will want only after they get a bit better at OH 3 in general.

And even with that limitation, the Getting Started Tutorial is starting to become overwhelming or too long.

  1. I think that should be clear now with the rewrite but if not I can add it.

  2. That belongs in the reference docs, not the Getting Started Tutorial. I believe Yannick has already written or is writing that.

  3. That too belongs in the reference docs, not the Getting Started Tutorial. I know that is a work in progress.

  4. That goes in the reference docs.

  5. That goes in the reference docs.

  6. That goes in the reference docs, or perhaps a separate building widgets tutorial.

  7. That goes in the reference docs.

  8. The reference docs or a separate building widgets tutorial.

  9. That was covered in a post from Yannick somewhere and should definitely be in the reference docs. I’ll have to think about whether to include it in Getting Started. While I don’t plan on covering “everything you need to know about how to build a custom widget” I do want to provide just a little bit about how to populate the Overview tab of the Overview Page.

  10. That should already be covered. I’ll make sure that it’s covered in the rewrite. Changes to the default widget settings on the Item will not be reflected on the pages where the widget was added from the model. You’ll have to remove and readd it to pick up the changes.

  11. It helps to use the Developer Sideboard to test expressions. Beyond that my recommendation is to file an issue to work out what is possible and how to make it more exposed to users.


2 -> Layout Pages | v3 Documentation Preview
3 -> openhab-webui/bundles/org.openhab.ui/doc/components at doc-component-reference · ghys/openhab-webui · GitHub (index page), purely generated from the definitions for now but will be modified with example sections, screenshots, more detailed descriptions
5 -> Building Pages: Components & Widgets | v3 Documentation Preview
9, 10 -> Layout Pages | v3 Documentation Preview



Thanks a lot, thats extremely useful information! Maybe I’ve overlooked something, but the link to the preview docs has not been posted in this thread so far, so I guess many other users have not known it either.

Why don’t you put it on the official OH docs page? I know it’s not complete yet and needs further review, but this documentation is >way better< than no documentation :slight_smile: and (I guess) many people are struggling because of that.

Probably because the ink on those pages didn’t dry until now-minutes.

1 Like

Thank you @ysc for your cool and detailed documentation and of corse for the new impressive UI! :partying_face:

Your documentation helped me a lot to get started! Something where I needed extra information was on integrating my own custom icons in the new main UI.
Luckily the community forum helped me to find the solution. I wrote the workflow down and I thought maybe it is useful for others, when they start building their own main UI widgets and crafting / designing their own icons.

I hope this “self” advertising of a community post is welcomed. If not, please let me know! Thanks :slight_smile:

is it possible to have an opacity to a widget color in the oh-label-cell, so let´s say 80% transparency of a color “white”, so that the background shines thru?

Totally possible for all custom widgets build upon f7-components - not possible for the standard oh-components as their background is fixed (besides the limited configuration properties that they might have).

Thanks Rainer. Got it!

Hello Reiner,

I have tried to copy your code into the “create Widget” section.
It looks like some stupid mistake, but I have no idea how to run your code.
-> Could you share the complete code?

I try to create a simple Widget like this:

Hey @SmartHome4all

you need a root component, which all of the other components will sit in. Normaly you would use something like f7-card, f7-block or f7-page here.
Notice that you dont need to write the leading - on the root component.

So it would look like:

component: f7-card
  title: Test
    - component: f7-button
1 Like

I successfully created a transparent f7-card that turns white once the item is “on”. I am struggling to understand to make the whole card clickable, my current workaround is a transparent button at the bottom. Can someone point me in the right direction how to make the f7-card ?



uid: widget_f7-card_test_v2
tags: []
    - description: A text prop
      label: Prop 1
      name: prop1
      required: false
      type: TEXT
    - context: item
      description: An item to control
      label: Item
      name: item
      required: false
      type: TEXT
  parameterGroups: []
timestamp: Feb 3, 2021, 3:13:27 PM
component: f7-card
    border-radius: var(--f7-card-expandable-border-radius)
    box-shadow: var(--f7-card-expandable-box-shadow)
    background-color: '=(items[props.item].state === "ON") ? "white" : "transparent"'
    - component: f7-block
          margin: 0px
          padding: 0px
          - component: f7-icon
              f7: '=(items[props.item].state === "ON") ? "lightbulb_fill" : "lightbulb"'
              size: 24
              margin: 0px
              padding: 0px
              color: '=(items[props.item].state === "ON") ? "yellow" : "black"'
          - component: Label
              text: =props.prop1
                font-size: 14px
                font-weight: 500
                margin: 0px
                padding: 0px
                color: '=(items[props.item].state === "ON") ? "black" : "black"'
          - component: Label
              text: '=(items[props.item].state === "ON") ? "AN" : "AUS"'
                font-size: 11px
                font-weight: 500
                color: '=(items[props.item].state === "ON") ? "red" : "black"'
          - component: oh-button
              action: toggle
              actionItem: =props.item
              actionCommand: ON
              actionCommandAlt: OFF
              position: absolute
              width: 250%
              height: 250%
              color: '=(items[props.item].state === "ON") ? "white" : "transparent"'
1 Like