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

c_r · January 29, 2021, 10:57am

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:

What’s the purpose of the built-in Overview Page, what/why is it different from other pages?
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.
Overview about all built-in OH widgets, their purpose, configuration options and visual demo (similar to F7 docu and kitchen sink)
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?
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”?
Styling: How can styling (margin/padding/colors/shadows) of built-in components (–f7 CSS Variables) be changed?
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
How can custom widgets be nested (e.g. a arbitrary number of custom list-items into a custom list)?
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)?
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?
how can a user debug the page/widget design (often the preview shows a blank page after code changes)?

rlkoshak · January 29, 2021, 4:28pm

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.

I think that should be clear now with the rewrite but if not I can add it.
That belongs in the reference docs, not the Getting Started Tutorial. I believe Yannick has already written or is writing that.
That too belongs in the reference docs, not the Getting Started Tutorial. I know that is a work in progress.
That goes in the reference docs.
That goes in the reference docs.
That goes in the reference docs, or perhaps a separate building widgets tutorial.
That goes in the reference docs.
The reference docs or a separate building widgets tutorial.
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.
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.
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.

ysc · January 29, 2021, 9:13pm

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

WIP PRs:

[WIP] Add UI section by ghys · Pull Request #1464 · openhab/openhab-docs · GitHub
[WIP] Add generated component reference by ghys · Pull Request #864 · openhab/openhab-webui · GitHub (reference pages)

c_r · January 30, 2021, 10:01am

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 and (I guess) many people are struggling because of that.

opus · January 30, 2021, 10:08am

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

secureHAB · January 31, 2021, 5:11pm

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

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

muelli1967 · February 2, 2021, 3:04pm

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?

RGroll · February 2, 2021, 3:59pm

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

muelli1967 · February 2, 2021, 4:01pm

Thanks Rainer. Got it!

SmartHome4all · February 2, 2021, 5:07pm

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:

RGroll · February 2, 2021, 5:20pm

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
config:
  title: Test
slots:
  default:
    - component: f7-button
    ...

muelli1967 · February 3, 2021, 5:06pm

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 ?

yaml:

uid: widget_f7-card_test_v2
tags: []
props:
  parameters:
    - 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
config:
  style:
    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"'
slots:
  content:
    - component: f7-block
      config:
        style:
          margin: 0px
          padding: 0px
      slots:
        default:
          - component: f7-icon
            config:
              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
            config:
              text: =props.prop1
              style:
                font-size: 14px
                font-weight: 500
                margin: 0px
                padding: 0px
                color: '=(items[props.item].state === "ON") ? "black" : "black"'
          - component: Label
            config:
              text: '=(items[props.item].state === "ON") ? "AN" : "AUS"'
              style:
                font-size: 11px
                font-weight: 500
                color: '=(items[props.item].state === "ON") ? "red" : "black"'
          - component: oh-button
            config:
              action: toggle
              actionItem: =props.item
              actionCommand: ON
              actionCommandAlt: OFF
              position: absolute
              width: 250%
              height: 250%
              color: '=(items[props.item].state === "ON") ? "white" : "transparent"'

RGroll · February 3, 2021, 5:27pm

Hey @muelli1967

it seems you were already on the right track - you only missed the style: property in your oh-button.

If you just want to make the card sending a fixed command to an item, it would be enough to overlay the whole card with a oh-link component (you could also use the oh-button component here, if you like the hover effect), like this:

uid: widget_f7-card_test_v2
tags: []
props:
  parameters:
    - 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
config:
  style:
    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"'
slots:
  content:
    - component: f7-block
      config:
        style:
          margin: 0px
          padding: 0px
      slots:
        default:
          - component: f7-icon
            config:
              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
            config:
              text: =props.prop1
              style:
                font-size: 14px
                font-weight: 500
                margin: 0px
                padding: 0px
                color: '=(items[props.item].state === "ON") ? "black" : "black"'
          - component: Label
            config:
              text: '=(items[props.item].state === "ON") ? "AN" : "AUS"'
              style:
                font-size: 11px
                font-weight: 500
                color: '=(items[props.item].state === "ON") ? "red" : "black"'
    - component: oh-link
      config:
        action: toggle
        actionItem: =props.item
        actionCommand: ON
        actionCommandAlt: OFF
        style:
          position: absolute
          width: 100%
          height: 100%
          top: 0
          left: 0

muelli1967 · February 3, 2021, 5:33pm

Thanks Rainer for the support. Yep, i missed that oh-link option. Works perfect now!

muelli1967 · February 3, 2021, 10:05pm

Just a feedback, i was replacing full tranaparent with a hex code color and a suffix „Hex Opacity Value“ . Here i uses suffix 73 for 45% transparency of the color white „#ffffff73“ when the item is off. Full white for ON.

Looks like this now:

Christopher_Hemmings · February 4, 2021, 3:11am

I prefer to use RGBA for colours
RGBA (255,255,255,0.1) or (255,255,255,1)

Richie1972 · February 8, 2021, 1:43pm

Hi, Popover class got mentioned around post 67, but I’m still struggling with the whole Framework7 to OH3 yaml interfacing.
Any ideas if these can be implemented:

close-by-backdrop-click	boolean	true	When enabled, popover will be closed on backdrop click. By default inherits same app parameter value
close-by-outside-click	boolean	true	When enabled, popover will be closed on when click outside of it. By default inherits same app parameter value
close-on-escape	boolean	false	When enabled, popover sheet will be closed on ESC keyboard key press

Thanks,
Richie

RGroll · February 8, 2021, 2:26pm

Hey @Richie1972

you have to assign the popover action to a oh-action-component, like oh-link or oh-button and refer its class to the popover component.

To see all available config options in the editor, press CTRL + Space.

    - component: oh-button
      config:
        title: Something
        action: popover
        fill: true
        text: Click me!
        popoverOpen: .popOver
    - component: f7-popover
      config:
        class: popOver
        closeByBackdropClick: true
        closeByOutsideClick: true
        backdrop: false
        closeOnEscape: true
      slots:
        default:
          - component: Label
            config:
              text: Some content!

Hope this helps!

Richie1972 · February 9, 2021, 9:08am

Hi,
Thanks for that.
That’s helped me for another issue I was having, but for this one I went with adding a button to the popover:

component: oh-button
config:
fill: true
text: X
class:
popover-close
style:
position: absolute
top: 4px
right: 2px

Thanks,
Richie

kklausl · February 15, 2021, 11:33am

I solved this for me: I use “items.###.displayState” . I think “displayState” uses the “Pattern” which you can define resp add through Metadata “stateDescription” of the “Item”. There you have to fill in %.2f (which defines 2 decimal numbers)