JSON-Pfade und Templates¶

Viele Teile der App lesen oder schreiben Daten über JSON-Pfade. Diese Seite fasst die Syntax und das Laufzeitverhalten zusammen.

JSON-Pfade¶

Die App nutzt eine einfache Pfadsprache ohne Wildcards.

Unterstützte Syntax¶

state
room.temperature
rooms[0].name
available_scenes[2].label
$ für den gesamten Root-Wert

Nicht unterstützt¶

*
rekursive Suchen
Filterausdrücke
Array-Slices

Leseverhalten¶

Intern liest JsonPathResolver Werte so:

read(root, path) liefert JsonElement?
readAsString(root, path) liefert String?
stringify(element) wandelt Primitive und Objekte lesbar in Text um

Wenn ein Pfad nicht existiert:

kommt null heraus
TextSourceConfig.fallback kann diesen Fall abfangen

Sonderfall Root-Wert:

mit $ liest du den kompletten Root-Wert
das ist besonders praktisch für Endpoints, die nur einen primitiven Wert wie on, 42 oder true liefern

Template-Syntax¶

Templates nutzen doppelte geschweifte Klammern:

{{grid.draw_watts}} W | PV {{pv.watts}} W

Jeder Platzhalter ist intern ein JSON-Pfad.

Beispiel für primitive Antworten:

Status: {{$}}

Wenn ein Pfad nicht existiert:

wird er durch einen leeren String ersetzt

Danach bereinigt die App überflüssige Leerzeichen vor Zeilenumbrüchen und trimmt den Gesamtausdruck.

Typische Einsatzorte für Pfade¶

title.value bei mode = "path"
value.value bei mode = "path" oder mode = "template"
icon.namePath
colorRules[].when.path
slider.valuePath
select.valuePath
select.optionsPath
select.optionValuePath
select.optionLabelPath
shutter.valuePath
RequestActionValueBindingConfig.path

Pfade in Select-Optionen¶

Bei optionValuePath und optionLabelPath wird relativ zum jeweiligen Optionsobjekt gelesen.

Beispiel:

"available_scenes": [
  {
    "id": "movie",
    "label": "Filmabend"
  }
]

Dann funktionieren:

optionValuePath = "id"
optionLabelPath = "label"

Bedingungen für Farbregeln¶

Beispiele:

Wahrheitswert prüfen¶

{
  "path": "open",
  "truthy": true
}

Numerischen Bereich prüfen¶

{
  "path": "grid.draw_watts",
  "greaterThan": 0.0
}

Regulärer Ausdruck¶

{
  "path": "state",
  "matches": "^(on|open)$"
}

Schreiben in JSON über Pfade¶

JsonPathUpdater.upsert(...) wird für Action-Bindings und optimistische Updates verwendet.

Eigenschaften:

legt fehlende Zwischenobjekte automatisch als leere JSON-Objekte an
arbeitet nur mit Objektpfaden wie room.level
Arrays werden beim Schreiben derzeit nicht erweitert