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

Hey @rlkoshak,

I totaly agree and also trying to write down some notes of the steps I take while creating my widgets.
But I realized, that it’s kinda hard finding a balance between ‘basic’ custom widgets (without too many classes and styles, which might overwhelm people) and those that are fullfills a real life usecase AND looking good but mostly depends on the usage (and styling) of standard components.

Sounds like a good idea starting with a widget which would be useful for a lot of people and also fullfills the above mentioned limited complexity - what applies here I think.

You can set-up the width of a widget via the ‘Column Options’, individually for each page. The fact, that it creates 3 rows of widgets is related to the use of the component ‘oh-grid-row’.

But this isn’t anything to worry about at all, as the height of the row depends on the largest widget it holds.

The components ‘oh-block’, ‘oh-grid-row’ and ‘oh-grid-col’ are components which were intended to use specifically to match the layout pattern of the pages and so it`s by design that they might extend over multiple rows.

If you just don’t want you components ‘flying’ exchange you ‘oh-block’ root component with a ‘f7-card’-

Which is more arguable, is the usage of pre-made widget-components (like ‘oh-image-card’, ‘oh-player-card’ and so on) inside another widget, whom have styles and classes already applied to them and were build upon the idea that they works as a standalone widget. They are easy to set-up and can be used without fiddling around with the YAML-structure whatsoever.
You can do this, but might loose some flexibility and be forced to remove some of the already applied classes again to make them look nice inside a custom-widget. (like removing borders, shadows and so on)

All of the things I’m talking about here are based on my current knowledge and the experiences I made so far - so take them with a grain of salt. I’m sure @ysc could give you a much more profound answer here.

Another approach (which I personally prefer) would be to use ‘smaller’ components (which the pre-defined components are based on) and rearrange / style them to your needs.

As an example let’s take your widget-idea from above, split it up and try to recreate it with ‘smaller’ components…
From what I understand, you would like to have a frame with 3 rows of contents (1st row: Image of the played media; 2nd row: player controls on the left / volume control and stop button on the right; 3rd row: Name of the currently used app) inside and some basic logic (like hiding elements based on item-status).


So the first thing here would be some card around your content to make it look like a single usable widget. ‘f7-card’ would be the right choice here, as its meant to act as a holder for different widget-components and you can already apply some basic informations like a title, footer, background-color and so on.

component: f7-card
  title: Chromecast widget example

1st row

Now we create the first row inside that card, which should hold the image of the played content. So ‘oh-image’ would be a good fit to that requirement as we can define an image-url here as well as an item, which holds an image(-url).

    - component: f7-block
          - padding
          - component: f7-row
                - component: oh-image
                      width: 100%
                      height: auto

You might ask, what the reason for the f7-block component is, which the content (f7-row) is sitting in.
We will use this as a container around all the components inside the content area of the widget which we can apply styles and classes to later on. The ‘style’ part inside the oh-image component just makes our image responsive in width and height.

I added an image url for demonstration purposes to the ‘oh-image’ component.

2nd row

The second row should have 2 columns in which we can put the different components. Each column will adapt to the available space which it sits in - so it will use 50% of the row each in our example.

Instead of ‘oh-player-item’ (which is normaly used as a component inside a ‘oh-list’) we use the standalone version of this control-component which is called ‘oh-player-controlls’ inside the first column and doing the same for ‘oh-slider’ (instead of ‘oh-slider-item’) as well as ‘oh-button’ (instead of ‘oh-label-item’) in the second column.

          - component: f7-row
                - padding-top
                - padding-bottom
                - component: f7-col
                      - component: oh-player-controls
                          item: =props.prefix+"_MediaControl"
                - component: f7-col
                      - component: oh-slider
                          item: =props.prefix+"_Volume"
                          min: 0
                          max: 100
                          step: 10
                          unit: %
                          label: true
                      - component: oh-button
                          text: Stop
                          iconF7: stop
                          fill: true
                          color: red
                          action: command
                          actionCommand: ON
                          actionFeedback: Media Stopped
                          actionItem: =props.prefix+"_Stop"
                            - margin-top

3rd row

Now to the 3rd row which should show the title of the currently played app.
This could be realized with a simple component named ‘Label’ which is nothing else than what it says, a label… :slight_smile:
As we`re using this basic component, we have to apply some styles to it to make it fit our needs.

          - component: f7-row
                - padding-top
                - justify-content-center
                border-top: 1px solid lightgray
                - component: Label
                    text: YouTube Music
                      font-size: 24px

If you then want to hide some components based on item states, I would do that with the ‘visible:’ configuration feature and an expression which you have to add to the corresponding component.

All of the above should look like this…



So I am not alone!

My present problems:

How to find the correct wording for the needed control/ element ( or whatever wording should be used in this context), for example a list from which an element could be selected.
How to dynamically fill such list (with items).

1 Like

I was struggling to find this one as well, Yannick to the rescue! You have to do it via an action, specifically the “options” action. I used a label card and linked the label and action to the same item. The options are pulled automatically from commandDescription metadata or can be provided in the widget properties.

Is there any example on how to format an item’s state with an expression?
I’ve searched on github ( and this thread and found none.

I’m having an item with state ‘9999,32 Wh’ and want to output it on a label card to ‘9,99 kWh’ - so converting using units of measurement and formating the number.

I’ve had no success using as expression ‘=format("%,.02f kWh", item.state)’ :frowning:

I’m not positive on this but I think there is both a .displayState and a .state on the item. I would expect that you can define displayState either from the item label or the state description metadata. I’ve not played with that though. so I could be easy off.

As for the rest i think I need to suggest and get this out some. But over all your version of the chromecast widget looks exactly like what I was going for. I agree that in the beginners tutorial we want to stick as much as possible to what can be done without editing the code by hand. More to follow after I play with it a bit…

Not much to add besides @RGroll has already said here.

Yes it’s an object but it can have either only state or both state and displayState, depending on whether you have a pattern/transformation applied or not.
To be on the safe side in your expressions you can use this syntax:

=items.MyItem.displayState || items.MyItem.state

It will use displayState and fall back to state if it’s not truthy.

I believe we should also link to useful CSS resources to help developing widgets, notably:

  • This has a list of the CSS properties that you can use on most components in the style parameter.

You’ll even find nice “play it” interactive examples like these:

  • These are all the CSS variables that you have in Framework7, some at the root level, some for a particular component, you can also override them or reference them in CSS like so:
--f7-text-color: red               // override
color: var( --f7-text-color)       // reference
  • This illustrates quite nicely how to make “Flexbox” layouts in CSS:

How can I format the display state format in an item or format the state in a widget?

Item -> Add Metadata -> Set State Pattern

1 Like

I think in M5 it is

Item -> Add Metadata -> State Description -> Pattern
1 Like

You are right, sorry…


some of the material-icon are not shown correctly (i.e. microwave).
Is it a problem of F7, or some OH library to update?

Nice find - also the soup bowl and some other exciting icons are missing :stuck_out_tongue_closed_eyes:

It seems that other devs also had problems using some of the icons as the library isn’t mantained well by google anymore.

@ysc Any idea how to fix this?! There seems to be an updated library available as a fork, if this could help:

Or since that’s the library used by home assistant it gets regular home automation related updates. What would be cool is to be able to reference them in f7-icons. That remains to be seen.


Even better!

I like the fork you linked! It’s a drop-in replacement, no need to bother doing some automated stuff to keep it current, the latest release will go into OH3.0.

And it has the latest icons:


1 Like

I am still using the set from the knx user forum KNX Icons

More than 800 homeautomation icons

Hi - i am developing a custom widget where i want to pass an expression in the prop value. Is it possible?
Setting this text in the UI:

="Temp: "+items.Hall_Temperature.displayState+" Rh: "+items.Hall_Humidity.displayState

and using it as below in yaml:

text: =props.SecondaryFooter

results in:

any suggestions so that the expression passed in the UI for a prop is actually parsed rather than displayed as text?

Do you mean you want to type in the configuration of the widget such formula?
I don’t think it is possible to use formula outside the yaml.
I don’t know any possible combination of your widget you are planning but a solution could be to include 4 variable in the prop, for instance:

in the yaml: text = prop.text1 + [prop.item1].state + …

Not sure for the syntax, I have not checked … let’s try

Yes, instead of defining items as props, i wanted to ask for the expression itself in the widget config. You’re right its not working. But it works in config of standard widgets like oh-label-cell.

The only alternate is to define seperate items in props and then use those in the yaml

="Temp: "+items[props.temperatureItem].displayState+" Rh: "+items[props.hummidityItem].displayState