Parameters for widgets in OpenHAB

Tutorials & Examples
1

I was looking for some time for a description of parameterGroups: in connection with widgets and their props. Somehow I had expected that you could do something with it in connection with iterations. But it seems that you can only use it to structure the set widget props.

While searching, I found some possibilities for parameters:, but no coherent documentation with examples. So here are the possibilities I found.

parameters:

  • name
  • label
  • description
  • required
  • default
  • type
  • context
  • pattern
  • options
  • limitToOptions
  • readOnly
  • groupName
  • multiple

Still unclear to me are

  • unit
  • context (except item)
  • unitLabel
  • criteria

name

This is the identifier under which the element is then available in the widget. No spaces may appear in the name, for example.

label

The text can be read at the top of the input field. HTML elements are not analysed here.

description

The description appears below the input field. It may also contain simple HTML tags, even a link is permitted.

required

  • true
  • false

This field is used to specify whether an entry must be made or not, default is false.

default

Even if defaultValue appears from time to time in the forums, in the current versions the identifier is default. This allows me to specify a value that is always valid if no entry has been made in the input field. This only makes sense if required is set to false. Specifying a default value makes some case distinctions superfluous.

OpenHAB has a small problem here with the BOOLEAN type. It turns

default: true

when saving and reloading

default: "true"

and this is not a Boolean value. However, the default value set by OpenHAB is true, so that this specification can or must be omitted.

type

This field always appears, which suggests that there are several values here. However, I have only been able to find two so far:

  • TEXT
  • BOOLEAN
  • INTEGER
  • DECIMAL

If possible, do not link the BOOLEAN type with a default value, see above.

For number types, there are also the parameters

  • min (Decimal)
  • max (Decimal)
  • step (decimal)

context

Here, too, one could assume that there are several possible values (see below), but I only know examples with:

item

This setting is used to include an element from the list of items

pattern

I can use this element to specify a list of possible values. Only exactly these values can then be typed in. Error messages may be generated during input. The value list is entered in the form

pattern: green|red|yellow|orange

options

This is a nicer way of specifying values. The possible values are specified, as is usual with HTML forms, via pairs of value/label

  • value:
  • label:

limitToOptions

  • true
  • false

This element only makes sense in connection with options. If the value is set to false (default), free text input is still possible. If the value is set to true, then only a selection from the defaults is possible. The value also influences the display during input.

readOnly

  • true
  • false

The value cannot be changed in the form, the current value is only displayed.

groupName

Here you can specify which element group (parameterGroups) the entry should belong to. Elements of the same group are kept together in the input mask.

multiple

  • true
  • false

This makes sense in connection with items.

parameters:
  - name: test
    label: Test
    description: Only one test
    context: item
    required: false
    type: TEXT
    multiple: true

leads to an input window with a list of all items from which I can select several elements. I still have to try out how I can then use the resulting list.

parameterGroups:

Used to group input parameters and offers the option of providing additional descriptions for the respective group.

  • name
  • label
  • description

The description of the respective elements corresponds to that of the parameters.

Example

The following listing is based on my animation listing and is adapted so that I can show some elements.

uid: ud_widget_props_example
tags: []
props:
  parameters:
    - default: orange
      description: Color of path must be <b>one of</b> - green, red, yellow, orange
      label: Farbe des Pfades
      name: pathcolor
      required: false
      type: TEXT
      pattern: green|red|yellow|orange
    - default: 1;0
      description: Direction of animation
      name: direction
      required: false
      type: TEXT
      limitToOptions: true
      options:
        - label: forward
          value: 0;1
        - label: backwards
          value: 1;0
    - default: 8s
      description: Duration of animation
      label: Dauer der Animation
      name: duration
      required: false
      type: TEXT
      options:
        - label: 1 second
          value: 1s
        - label: 4 seconds
          value: 4s
        - label: 8 seconds
          value: 8s
    - default: red
      description: Color of circle
      label: Farbe des Kreises
      name: circlecolor
      required: false
      type: TEXT
      limitToOptions: true
      options:
        - label: Grün
          value: green
        - label: Rot
          value: red
        - label: Gelb
          value: yellow
    - default: "6"
      description: Radius of circle
      label: Radius des Kreises
      name: circleradius
      required: false
      type: INTEGER
      min: 1
      max: 8
    - description: Circle visible
      label: Kreis sichtbar
      name: visibleCircle
      required: false
      type: BOOLEAN
  parameterGroups: []
timestamp: Mar 29, 2024, 12:33:05 PM
component: f7-card
config:
  footer: =props.duration+(props.direction=='0;1'?' forward':' backwards')
  style:
    border: 3px solid green
    border-radius: 20px
    height: auto
    text-align: center
    width: 200px
  title: Watch animation!
slots:
  content:
    - component: svg
      config:
        style:
          height: 110px
          width: 200px
        xmlns: http://www.w3.org/2000/svg
      slots:
        default:
          - component: path
            config:
              d: M0,15 h20 q60,0 60,45 t60,45 h20
              fill: none
              id: examplepath
              stroke: =props.pathcolor
              stroke-width: 1
          - component: circle
            config:
              fill: =props.circlecolor
              r: =props.circleradius
              visible: =props.visibleCircle
            slots:
              default:
                - component: animateMotion
                  config:
                    dur: =props.duration
                    keyPoints: =props.direction
                    keyTimes: 0;1
                    repeatCount: indefinite
                  slots:
                    default:
                      - component: mpath
                        config:
                          xlink:href: "#examplepath"

The following window appears for the props:

600px-2024-03-29_12.31.47_89ae7a21f78b
600px-2024-03-29_12.31.47_89ae7a21f78b600×600 41.4 KB

You can see that the default values are entered here, but not the implicit default value for BOOLEAN.

For the duration specifications, I did without

 limitToOptions: true

Therefore, the defaults only appear if you delete the input field, but free entries such as 32s are also possible.

2 Likes
2

See also this older thread from @rlkoshak where he started to piece together some of this information as well, including a little more work with the context property:

Basically the context property only applies to a TEXT parameter and it tells the UI which type of text field input to use. Because a basic text field could be so many different things, the UI needs the extra help to know what this particular text field is referring to. So, a context of item will bring up the item selector, but a context of rule will bring up the rule selector. If you just want the field to be plain old text that you type in, then don’t add a context property.

There are many possible values for context and not all of them make sense for the widget editor (e.g. qrcode or persistenceService). This same system of parameters is reused in many different locations throughout the UI. So, pretty much anything somewhere else in the UI that you can find in where you get to select something or input a value is represented in this context property. For widgets, I’d say the only ones that are really likely to be of use are:

  • item
  • rule
  • time
  • widget
  • page
    widget and page are special in that 1) you need to specify them as array elements and 2) as a result, you can specify both on one parameter if you want to have a list that include widgets and pages:
context:
  - widget
  - page

I don’t believe these others (except for context) are likely to come up at all in the widget props. As with the context values, there are some general properties that don’t really have an application to widgets specifically.

This is related to how the yaml is processed back and forth with the json storage. It’s best if you just use 0 and 1 to set defaults for the BOOLEAN type.

These are the only viable options for type. All other distinction is handled using the context property.

This is handled like an HTML input tag’s pattern attribute which means that it actually accepts regex to test if the input value is valid. For example

pattern: "[0-9]{5}"

Will only accept 5 digit numbers (if for some reason you needed US zip codes in your widget).

Your example of green|red|yellow|orange is actually just regex specifying that only exact matches of those four words are valid. If you used green|r[aeiou]d|yellow|orange then rad, rid, rod, and rud would also be valid.

If you receive multiple values from a parameter than the prop will be an array that you use in the expression like any other array (e.g., props.itemList[1]) or as the source array for a repeater:

- component: oh-repeater
  config:
    in: =props.itemList
3

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.