OpenHAB-parameters

Aus Debacher-Wiki
Zur Navigation springenZur Suche springen

Ich war einige Zeit auf der Suche nach einer Beschreibung für parameterGroups: im Zusammenhang mit widgets und deren props. Irgendwie hatte ich erwartet, dass man damit etwas im Zusammenhang mit Iterationen anfangen könnte. Es ist aber wohl so, dass man damit nur die Set widget props strukturieren kann.

parameters:

Bei der Suche habe ich aber nebenbei einige Möglichkeiten für parameters: gefunden, aber keine zusammenhängende Dokumentation mit Beispielen. Daher hier einmal das, was ich so an Möglichkeiten gefunden habe.

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

Noch unklar sind mir:

  • unit
  • context (außer item)
  • unitLabel
  • criteria

name

Das ist der Bezeichner, unter dem das Element dann im widget verfügbar ist. Im Namen dürfen z.B. keine Leerzeichen auftauchen.

label

Der Text ist oben im Eingabefeld zu lesen. HTML-Elemente werden hier nicht ausgewertet.

description

Die Beschreibung taucht unterhalb des Eingabefeldes auf. Sie darf auch einfache HTML-Tags beinhalten, sogar ein Link ist erlaubt.

required

  • true
  • false

Mit diesem Feld wird festgelegt, ob eine Eingabe erfolgen muss oder nicht, default ist false.

default

Auch wenn in den Foren immer mal wieder defaultValue auftaucht, in den aktuellen Versionen ist der Bezeichner default. Damit kann ich einen Wert vorgeben, der immer dann gültig ist, wenn keine Eingabe in das Eingabefeld erfolgt ist. Das macht also nur Sinn, wenn required auf false steht. Die Angabe eines default-Wertes macht manche Fallunterscheidung überflüssig.

OpenHAB hat hier ein kleines Problem beim Type BOOLEAN. Es macht aus

default: true

beim Speichern und neu laden

default: "true"

und das ist kein Boolean-Wert. Der von OpenHAB gesetzte Default-Wert ist aber true, so dass man auf diese Angabe verzichten kann bzw. muss.

type

Dieses Feld taucht eigentlich immer auf, was den Verdacht nahelegt, dass es hier mehrere Werte gibt. Ich habe aber bisher nur zwei finden können:

  • TEXT
  • BOOLEAN
  • INTEGER
  • DECIMAL

Den Typ BOOLEAN möglichst nicht mit einem default Wert verknüpfen, s.o.

Bei Zahlentypen gibt es noch die Parameter

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

context

Auch hier könnte man annehmen, dass es mehrere mögliche Werte gibt (s.u.), ich kenne aber nur Beispiele mit:

  • item

Mit dieser Einstellung wird eine Element aus der Liste der Items eingebunden

pattern

Mit diesem Element kann ich eine Liste von möglichen Werten vorgeben. Nur exakt diese Werte können dann eingetippt werden. Bei der Eingabe werden ggf. Fehlermeldungen generiert. Die Eingabe der Werteliste erfolgt in der Form:

pattern: green|red|yellow|orange

options

Dies ist eine nettere Möglichkeit um Werte vorzugeben. Die Möglichen Werte werden, wie bei HTML-Formularen üblich, angegeben über Paare von value/label

  • value:
  • label:

limitToOptions

  • true
  • false

Dieses Element macht nur im Zusammenhang mit options Sinn. Steht der Wert auf false (Vorgabe) dann ist trotzdem eine Freitext-Eingabe möglich. Steht der Wert auf true, dann ist nur eine Auswahl aus den Vorgaben möglich. Der Wert hat auch Einfluss auf die Darstellung bei der Eingabe.

readOnly

  • true
  • false

Der Wert kann im Formular nicht verändert werden, der aktuelle Wert wird nur angezeigt.

groupName

Hiermit kann ich angeben, zu welcher Elementgruppe (parameterGroups) der Eintrag gehören soll. Elemente der gleichen Gruppe werden in der eingabe-Maske zusammen gehalten.

multiple

  • true
  • false

Dies macht Sinn im Zusammenhang mit items.

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

führt zu folgendem Eingabefenster:

2024-03-29 10.49.09 89ed30418aa0.png

einer Liste aller Items, aus der heraus ich mehrere Elemente anwählen kann. Ich muss noch ausprobieren, wie ich die entstehende Liste dann nutzen kann.

Noch unklare Nützlichkeit

Die folgenden Möglichkeiten habe ich bei meinen Recherchen gefunden, aber noch keine Anwendung oder keine Beschreibung für die Nutzung gefunden.

unit

unit="A|cd|K|kg|m|mol|s|g|rad|sr|Hz|N|Pa|J|W|C|V|F|Ω|S|Wb|T|H|Cel|lm|lx|Bq|Gy|Sv|kat|m/s2|m2v|m3|kph|%|l|ms|min|h|d|week|y"

Noch unklar was man damit machen kann

context

{network-address|serial-port|password|password-create|color|date|datetime|email|month|week|dayOfWeek|time|tel|url|item|thing|group|tag|service|channel|rule|location}

unklar ausser item

unitlabel

unklar

criteria

unklar

parameterGroups:

Dient dazu Eingabe-Parameter zu gruppieren und bietet die Möglichkeit zusätzliche Beschreibungen für die jeweilige Gruppe zu liefern.

  • name
  • label
  • description

Die Beschreibung der jeweiligen Elemente entspricht der bei den Parametern.

Anwendungs-Beispiel

Das folgende Listing basiert auf meinem Animations-Listing und ist so angepasst, dass ich einige Elemente zeigen kann.

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"

Es ergibt sich Folgendes Fenster für die props:

2024-03-29 12.31.47 89ae7a21f78b.png

Man sieht, dass die default-Werte hier eingetragen sind, aber nicht der implizite Default-Wert bei BOOLEAN.

Bei den Dauer-Angaben habe ich auf

 limitToOptions: true

verzichtet. Daher erscheinen die Vorgaben nur, wenn man das Eingabefeld löscht, dafür sind aber auch freie Eingaben wie 32s möglich.

mit paramGroups

Im nächsten Schritt habe ich die parameterGroups mit genutzt:

uid: ud_widget_props_example_groups
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
      groupName: colorGroup
    - default: 1;0
      description: Direction of animation
      name: direction
      groupName: animationGroup
      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
      groupName: animationGroup
      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
      groupName: colorGroup
      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
      groupName: colorGroup
      required: false
      type: BOOLEAN
  parameterGroups: 
    - name: animationGroup
      label: Animation
      description: animation see <a href="https://community.openhab.org/t/animations-with-openhab/154747">example at OpenHAB</a>
    - name: colorGroup
      label: Farben
      description: colours  
...

Die unveränderten Zeilen sind hier nicht noch einmal mit dargestellt.

Jetzt ergibt sich für die props Eingabe folgendes Bild

2024-03-29 12.42.57 b7ee7d802c97.png

Man sieht hier, dass auch die Reihenfolge der Gruppen für die Darstellung eine Rolle spielt. Einzelne Parameter, die nicht zu einer Gruppe gehören, kommen zuerst.

Vollständig?

Mir ist nicht klar, ob ich jetzt alle Möglichkeiten der props hier gefunden habe. Für weitere Informationen bin ich dankbar.