Aktionen und Dialoge¶

Diese Seite dokumentiert alle Aktionsarten sowie die typspezifischen Dialog-Widgets.

WidgetActionConfig¶

WidgetActionType¶

Endpoint-Aktionen¶

Normale klickbare Widgets verwenden action.type = "endpoint" oder lassen type weg.

Ohne request.method gilt dieselbe Auto-Regel wie bei Status-Requests:

• kein Body -> GET
• Body vorhanden -> POST

Beispiel:

"action": {
  "request": {
    "url": "http://192.168.1.20/api/lights/living-room/toggle"
  },
  "prompt": true,
  "refreshAfterAction": true
}

Bestätigungsdialoge mit prompt¶

Für Aktionen mit spürbarer Wirkung kann ein vorgeschalteter Bestätigungsdialog aktiviert werden.

Mögliche Stellen:

• widgets[].action.prompt für normale Tap-Aktionen und Slider-Widgets
• widgets[].content.select.action.prompt für Select-Bestätigungen
• widgets[].content.shutter.sliderAction.prompt für die Zielposition im Rollladen-Dialog
• widgets[].content.shutter.upAction.prompt, stopAction.prompt, downAction.prompt für Rollladen-Kommandos

Laufzeitverhalten:

• der Dialogtitel nutzt den aktuell sichtbaren Widget-Titel; wenn keiner aufgelöst werden kann, fällt die App auf die Widget-ID zurück
• der Dialogtext ist aktuell generisch und nicht pro Widget konfigurierbar
• erst nach Bestätigung wird der eigentliche Request ausgeführt

Beispiel für einen bestätigten Aktionsbutton:

{
  "content": {
    "mode": "icon_text",
    "title": {
      "mode": "static",
      "value": "Warmwasser jetzt"
    }
  },
  "action": {
    "request": {
      "url": "http://192.168.1.20/api/hot-water/boost-now"
    },
    "prompt": true,
    "refreshAfterAction": true
  }
}

Tab-Wechsel¶

"action": {
  "type": "switch_tab",
  "targetTabId": "energy"
}

Validierung:

• targetTabId muss auf einen existierenden Tab verweisen

URL im Browser öffnen¶

"action": {
  "type": "open_url",
  "url": "https://example.org/camera/frontdoor"
}

Validierung:

• dieselbe URL-Policy wie bei normalen Requests

Slider-Widgets¶

Ein Slider-Widget benötigt zwei Bereiche:

• content.slider für Bereich, Step und Statuspfad
• action.request für den eigentlichen Action-Endpoint

WidgetSliderConfig¶

Dialogverhalten:

• Tap öffnet Slider-Dialog
• Statuswert setzt die aktuelle Slider-Position
• OK sendet den neuen Wert
• bei refreshAfterAction = false erfolgt ein optimistisches Snapshot-Update

Select-Widgets¶

WidgetSelectConfig¶

SelectActionConfig¶

Dialogverhalten:

• Tap öffnet ein Select-Feld
• Optionen kommen aus dem Status
• primitive Arrays wie ["A","B"] funktionieren ebenso wie Objektarrays
• prompt: true zeigt vor dem eigentlichen Senden einen zusätzlichen Bestätigungsdialog
• bei erfolgreicher Bestätigung kann der Snapshot optimistisch aktualisiert werden

Beispiel mit Bestätigung:

"select": {
  "valuePath": "mode",
  "optionsPath": "available_modes",
  "action": {
    "request": {
      "url": "http://192.168.1.20/api/heating/mode",
      "method": "post",
      "jsonBody": {
        "mode": ""
      }
    },
    "valueBindings": [
      {
        "target": "json_body",
        "path": "mode"
      }
    ],
    "prompt": true
  }
}

Rollladen-Widgets¶

WidgetShutterConfig¶

ShutterSliderActionConfig¶

Dialogverhalten:

• der Slider samt OK-Button erscheint nur, wenn sliderAction gesetzt ist
• die Kommando-Buttons liegen in einer Zeile als Runter, optional Stop, Hoch
• Stop erscheint zusätzlich im Dialog, wenn stopAction gesetzt ist
• Buttons und Slider können unterschiedliche Endpoints nutzen
• upAction, stopAction, downAction und sliderAction können jeweils unabhängig prompt: true setzen
• upAction, stopAction und downAction verwenden dieselbe WidgetActionConfig wie normale Widgets

Gemeinsame Binding-Struktur¶

Slider-, Select- und Rollladen-Slider verwenden denselben Binding-Typ.

RequestActionValueBindingConfig¶

RequestActionValueTarget¶

Beispiele für Bindings¶

Wert in JSON-Body schreiben¶

{
  "target": "json_body",
  "path": "brightness"
}

Wert in Header schreiben¶

{
  "target": "header",
  "key": "X-Level"
}

Wert in Query-Parameter schreiben¶

{
  "target": "query_param",
  "key": "position"
}

Erfolgs- und Fehlerverhalten¶

Bei erfolgreicher Aktion:

• refreshAfterAction = true: betroffenes Widget wird neu geladen
• refreshAfterAction = false: optimistisches Update, soweit für den Typ vorgesehen

Bei Fehlern:

• das Widget erhält hasError = true
• eine User-Message wird gesetzt
• laufende Dialoge verlassen den Busy-Zustand

Siehe auch¶

• Slider
• Select
• Rollladen