YAML for dummies, somewhere?

Add-ons UIs
1

I’m playing around with custom widgets, copy&pasting code snippets from different posts without really understanding what I`m doing. I see there is some kind of structure inside a YAML file, like props, config, slots, content etc. and I’d like to understand the basics of those parts. I’m reverse engineering from preexisting widgets and configs found on the forum but still have no complete picture.

can someone point me to a tutorial or how-to to better understand the basics/structure of an OH yaml file?
(eg. where’s the line under “Aquarium” coming from, why’s °C missing in the temperature curve and why does my custom card looks different to all others?..)

image
image693×369 12.5 KB

image
image1643×566 32.7 KB

[details=“yaml”]

uid: Aquarium
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: Jan 11, 2021, 3:43:55 PM
component: f7-card
config:
  style:
    --f7-safe-area-right: 0
    --f7-safe-area-left: 0
  action: group
  actionGroupPopupItem: gAquarium
slots:
  content:
    - component: oh-label-card
      config:
        noShadow: true
        trendItem: Aquarium_TemperaturWasser
        action: analyzer
        actionAnalyzerItems:
          - Aquarium_TemperaturWasser
        item: Aquarium_TemperaturWasser
        title: Aquarium
        icon: oh:temperature
        actionAnalyzerCoordSystem: time
        vertical: false
    - component: f7-row
      config:
        class:
          - padding
      slots:
        default:
          - component: f7-col
            slots:
              default:
                - component: oh-button
                  config:
                    action: toggle
                    actionItem: Aquarium_AquariumTageslicht
                    actionCommand: ON
                    actionCommandAlt: OFF
                    text: Tageslicht
                    fill: true
                    iconF7: sun_max
                    color: '=(items.Aquarium_AquariumTageslicht.state === "OFF") ? "red" : "green"'
          - component: f7-col
            slots:
              default:
                - component: oh-button
                  config:
                    action: toggle
                    actionItem: Aquarium_AquariumHintergrund
                    actionCommand: ON
                    actionCommandAlt: OFF
                    text: Hintergrundbeleuchtung
                    fill: true
                    iconF7: sun_haze
                    color: '=(items.Aquarium_AquariumHintergrund.state === "OFF") ? "red" : "green"'
          - component: f7-col
            slots:
              default:
                - component: oh-button
                  config:
                    action: toggle
                    actionItem: Aquarium_AquariumPumpe
                    actionCommand: ON
                    actionCommandAlt: OFF
                    text: Pumpe
                    fill: true
                    iconF7: gauge
                    color: '=(items.Aquarium_AquariumPumpe.state === "OFF") ? "red" : "green"'
          - component: f7-col
            slots:
              default:
                - component: oh-button
                  config:
                    action: toggle
                    actionItem: Aquarium_AquariumFutter
                    actionCommand: ON
                    actionCommandAlt: OFF
                    text: Futterautomat
                    fill: true
                    color: '=(items.Aquarium_AquariumFutter.state === "OFF") ? "red" : "green"'
[/details]
2

Hi,

unfortunately your YAML lost all its indents - and with that the structure.
YAML, just like python is nesting through indents (whitespace before your line), other languages use brackets to mark a clear hierarchy.
Now I am still on the same path as you are, but think of it as defining a HTML/CSS Page. You set the type of your page (f7-card) for example and then you add elements on the page, like a header, a footer, and nest other components like e. g. chips/tags. These components go under “slots” and can be further nested.

So where is your °C: An item can have a separate displaState where it will give you a string with unit, depending on how you set up your item.

3

Hello @powerpolly ,
I had your difficolties too.

I Understand what YAML really is and his pourpose when I watched these video .

After that I’d understand that the real difficoulties is to learn a bit of Framework7 typography classes , CSS variables , layout grid etc etc… bilions of “functions” witch is not easy to figure out if (like me) you never work with framework…

4

glad to see I’m not alone :wink:
I got the purpose of a YAML file, after all it’s nothing OH specific, I know.

But what I am looking for is a more “OH related” explanation of that YAML structure and coding. eg how to define your card design or what are the possible parameters you can choose if you want this or that. or see that “actionAnalyzerCoordSystem” parameter? no Framework7 stuff, isn’t it? it must be an OH related config option because Google has exactly 3 hits pointing to this community. so, how did the creator of this widget knew to use “actionAnalyzerCoordSystem”??? kind of man-pages somewhere?

but you’re probably right, I will need to dig further into html/CSS/f7 etc if I want to customize the really fancy and modern looking GUI even more for my needs.

EDIT: FYI adding %.1f %unit% as pattern to the item solves the missing unit in the widget too…

5

I share your frustration - I’m also trying to put together some widgets and it’s extra hard because:

The f7-stuff is not easy for someone with almos no CSS background and then wrapping this into another format (YAML) where some stuff is similar, some is not - no fun at all.

But, and this is a big one: We should be very very thankful for all the development that was put into it, now all that’s lacking is the documentation and examples - but that’s what we’re here for, right?

6

For this one in particular, it’s here - you’ll get the label, description and options when you configure the property with a property sheet, or with autocompletion in YAML editors:

But I agree it’s not ideal.

That’s something I’ve been planning to do - take descriptions from these files and also the framework7 docs (example framework7-website/src/pug/vue/list-item.pug at v5 · framework7io/framework7-website · GitHub) compile some Markdown pages for each widget with a script, and submit them to the docs as basis for a man-page style documentation.

2 Likes
7

I’m not complaining and not frustrated, I just try to switch my house automation experience to the next level.
Starting more than 3 years ago with a Smart light bulb I realized thats gonna be my next bad weather hobby. Since then I had a steep learning curve, starting as a typical MS-Office user I now run a 24/7 linux KVM server with a couple of nice services.
Automatism, transparency and stability were the main goals I focused on when starting home automation and I knew that choosing an open-source solution would mean a lot of learning, tweaking, soldering, engenieering and also failing. but hey, thats what a hobby should be! The only piece of openHAB I never succeeded was HabPanel. I was spending weeks and months to create nice dashboards, ideally one for each room, that looked simple and professional. Once I was close to a first usable draft, the wall-mounted tablet I built broke and so I bought a new one but guess what, it had a different display-resolution and wham, all that nice icons, layouts and textpanels were messed up like garbage and I threw the plan of a WAF and MILAF compatible UI away. since then my Wife and Mother-in-law must deal with Alexa, kinda love-hate relationship I would say. altough they could still control everything with its traditional switches I often catch them commanding Alexa to do things…

Then, with OH3 you developed that lovely modern UI which can intuitively change the screen depending on what and where you click and most important for me, independently of the size of the screen! Again I’ll find myself dealing with CSS etc but this time I can build upon some kind of a baseline, not from scratch like with happanel. I’m sure I’ll find my way, like many others in this forum already did. I just need to close that gap between the super easy setup and day-one tasks and the mega complex day-two tasks like customizing badges.

I really appreciate your efforts in developing such a cool and powerfull smart-home solution and I can hardly imagine how much time and head-ache you must afford to get all that up and running rock solid and stable. we can see your passion for this hobby in every single post you respond to, thanks a lot for that too!
so, now I’ll go back to your links and see what you’re trying to tell me. :wink:

cheers

5 Likes
8

I’m driving myself mad trying to figure out yaml. :sweat_smile: Is there a debugger or something that you can test the code in before pasting it into OH?
I find if there is something wrong OH will not save the widget. But it does not give any meaningful explanation.

My two issues are:

  1. indentation - I am just doing trial and error
    Even just cutting and pasting existing widgets seems to cause problems as soom as I remove a section the indentation messes up!

  2. keywords -
    default: what does this do is it necessay
    config: do you need to have these for every section
    May be just a basic cheat sheet for beginners specific to OH would be useful. Even a skeleton widget with explanation for the components. ( I presume YAML allows comments!)

3 Likes