Skip to content

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

mode = "template" und mode = "table" nutzen beide dieselbe Platzhalter-Syntax mit doppelten geschweiften 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.

Tabellen-Syntax für mode = "table"

Nach der Template-Auflösung interpretiert die App den fertigen Text bei mode = "table" als einfache Tabelle:

  • Zeilenumbruch trennt Rows
  • | trennt Spalten
  • führende oder abschliessende | sind optional
  • Markdown-Trennzeilen wie |---|---| oder |:---|---:| werden ignoriert

Beispiel:

Quelle | Leistung
Netz | {{grid.draw_watts}} W
PV | {{pv.watts}} W

oder im Markdown-Stil:

| Quelle | Leistung |
|--------|----------|
| Netz   | {{grid.draw_watts}} W |
| PV     | {{pv.watts}} W |

Typische Einsatzorte für Pfade

  • title.value bei mode = "path"
  • value.value bei mode = "path", mode = "template" oder mode = "table"
  • 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

Beispiel:

{
  "target": "json_body",
  "path": "payload.level"
}

Ausgangsbody:

{
  "payload": {}
}

Ergebnis nach Binding:

{
  "payload": {
    "level": 42
  }
}

Typische Fehler

  • falsche Schreibweise des Feldnamens
  • Array-Index existiert nicht
  • key und path verwechselt, z. B. bei Header-Bindings
  • Erwartung, dass Templates fehlende Werte automatisch formatieren

Empfehlung

  • flache und sprechende Felder bevorzugen
  • bei Select-Optionen einheitliche Objektstruktur verwenden
  • Templates nur für Anzeige, nicht für Logik verwenden
  • bei Action-Bindings möglichst eindeutige JSON-Pfade nutzen

Siehe auch