Need information of basic concepts of widgets in OH3

Setup, Configuration and Use Beginners
,
1

I’m looking for a starting point to create my own widgets in OH3.

Somewhere in the documentation I found the information that all UI components are based upon Framework7. This explains those shortcuts starting with f7- in the YAML-files of the widget definitions. But neither the F7 documentation, nor the OH docs explain which components could be nested?!

Each widget starts with a kind of header:

uid: test
tags: [test]
props:
  parameters:
    - description: Prefix for the items with the data
      label: Item prefix
      name: prefix
      required: false
      type: TEXT
  parameterGroups: []
timestamp: Jan 14, 2021, 7:52:35 PM
component: f7-card
config:
  title: Test

Questions:

  • What props-parameters-type's are possible?
  • Are hidden props-parameters possible?
  • Is timestamp required?
  • Which F7 component's could be used as base component?
  • Which properties (e.g. title, style) of the base component could be set?

In the follow up the widget seams to consist of other components. They could in some way nested. Is somewhere the concept of slots explained?

I do found some example widgets:

  • https:/github.com/rgrollfitz/oh3-widgets/
  • https:/community.openhab.org/t/create-a-simple-thermostat-widget-in-oh3/113553
  • https:/community.openhab.org/t/wiki-building-pages-in-the-oh3-ui-documentation-draft-2-3/104392
  • https:/community.openhab.org/t/openhab-3-0-my-getting-started-notes-model-and-pages/107204
  • …

But even with them, I do NOT get it. There seams to be a Label component. Why not ‘f7-label’ or ‘oh-label’. Other components do start with oh-? Which of them are available?

Sorry about this many questions! But maybe others can profit.

Any hints are welcome! Thanks in advance!

Achim

2

The YAML configuration of pages, widgets, etc. is used to render the html content in the openHAB single page application. That means, that the html is not rendered on the server but in the browser.

So you doing basically some kind of frontend web programming. Let’s take the f7-card for example. This component is from the framework7 vue components. The card documentation you can find here:

Card Vue Component

If you use this, it will render a <div> tag with the assigned attributes, class and style properties. As mentioned in the documentation the card has the attributes:

title, content, footer, padding, outline, no-shadow, etc.

Also the card slots like default, content, header and footer are documented there. Worth mentioning is that the default slot and content slot are the same from the point of f7. This is also mentioned in the documentation.

So in your example, if you want to add something to the f7-card, you simply have to give it a default slot. The documentation and the examples of f7 are pretty good to get a feeling what components are containers, that can host other components or just simple components.

I for myself started two weeks ago to design own pages and widgets and the learning curve is pretty steep.

If you look for specific requirements it is worth to search the forum for widgets. You will find tons of YAML code with explanations how they work.

Last word on the oh-* components. They are wrappers around the f7 components, but add functionality to handle interactions with the openHAB items. So if you want to show some state or interact with them by, e.g. pressing buttons, you have to take the oh component variants. Though be aware that they often do not expose the whole set of attributes of the underlying f7 components.

Hope this helps and get you motivated :slight_smile: to go along with OH3

5 Likes
3

Thanks a lot!

Your info gave me a good start. Hopefully I can share some results in the ongoing days, maybe weeks.

Achim

4

Hi.

Quick question and cannot find the answer.

What is the purpose of the dash in the widget code etc?
For example:

  • component: f7-row
    config:
    class:
    - button
    - button-fill
    - button-large
    - button-raised
    - align-items-center
    Is it just for ease of reading?
    If I remove the dashes it still works.

Thanks

5

I did share a lot of the original questions and your post really helps getting into it.

There is one thing not asked before, but might help digging deeper into that topic - is there some IDE that can be used for code completion, formatter and preview - other than the custom widget editor in the browser?
Performance could be better in my opinion and some CTRL-Space / CTRL-SHIFT-F support would be great! :wink:

6

If I have it correctly, the leading hyphen (-) means that they are part of a list

Fruit:
   - Apple
   - pear
   - banana

I’m just starting with YAML , so correct me if i’m wrong

7

As stated above, the questions asked here do indeed adress alot of the questions a beginner has. There is one though that remains unanswered, which is the ‘timestamp’ attribute, is that required?

Thank you @franks for your writeup, it was very informative, and well written to make things understandable. Cheers!