Widgets¶

Diese Seite beschreibt die vollständige Widget-Struktur unabhängig vom konkreten Widget-Typ.

WidgetConfig¶

Bearbeitung in der App¶

Die App bearbeitet Widgets in einem ganzseitigen Wizard mit Breadcrumbs.

• Grunddaten & Layout: ID, Modus, Größe, Zeilenverhalten; hier stehen auch Löschen und bei bestehenden Widgets Duplizieren
• Platzierung: Reihenfolge sowie Zuordnung zu Gruppen und Reitern
• Inhalt: Titel, Wert, Icon, Design und modusspezifische Inhalte als Akkordeons
• Status: Statusquelle und Antworttyp
• Aktion: Tap-Aktion, Overlay-Aktionen sowie bei Bild-Widgets die Bildaktionen

Zusätzliche Editorhilfen:

• Titel- und Wertquellen für path, template und table besitzen einen Path-Picker
• Icon-Felder besitzen eine suchbare Material-Icon-Auswahl
• Farbfelder besitzen einen Color-Picker, unterstützen aber weiterhin manuelle HEX-Werte
• beim Duplizieren übernimmt das neue Widget auch seine Platzierung in Gruppen und Reitern

WidgetLayoutConfig¶

WidgetSize¶

Zulässige Werte:

• 1/1 bis 4/4
• full/1 bis full/4

Semantik:

• 2/1 belegt zwei Spalten und eine Zeile
• 3/2 belegt drei Spalten und zwei Zeilen
• full/1 belegt immer die gesamte aktuell verfügbare Dashboard-Breite
• full/n startet auf einer neuen Zeile und wirkt wie ein Layout-Umbruch

WidgetContentConfig¶

Wichtige Laufzeitregeln:

• wenn title nicht gesetzt ist, rendert die App keinen automatisch erzeugten Default-Titel
• wenn value nicht gesetzt ist, bleibt der Wertbereich leer
• icon_text kann ohne status als reiner Button modelliert werden
• shutter darf ebenfalls ohne status vorkommen, wenn das Widget nur Befehle auslösen soll
• cover ist ein akzeptierter Alias für shutter

WidgetRenderMode¶

WidgetTypographyConfig¶

Wirkung:

• wenn null, verwendet die App die Material-Theme-Typografie
• wenn gesetzt, werden fontSize und lineHeight passend angepasst

WidgetColorsConfig¶

Wirkung:

• wenn nur tileColor gesetzt ist, verwendet die App automatisch eine kontrastreiche Standard-Schriftfarbe
• titleColor und valueColor bleiben optional und überschreiben nur die jeweilige Textart
• tileColorRules, titleColorRules und valueColorRules funktionieren wie bei Icons: die erste passende Regel gewinnt
• wenn keine Farbregel passt, verwendet die App die statischen Werte aus tileColor, titleColor und valueColor als Fallback
• Farbwerte sollten als #RRGGBB oder #AARRGGBB angegeben werden

WidgetIconConfig¶

Wichtige Laufzeitregeln:

• namePath hat Vorrang vor name
• wenn kein icon gesetzt ist, wird kein Fallback-Icon gerendert
• wenn kein Material-Icon aufgelöst werden kann, wird ein vorhandenes emoji gezeigt
• sizeDp überschreibt die Standardgrösse des führenden Icons
• Emojis lassen sich technisch nicht wie Material-Icons tinten, deshalb sind icon.name-basierte Widgets für dynamische Farben vorzuziehen

ColorRuleConfig¶

Die erste passende Regel gewinnt.

WidgetConditionConfig¶

Alle gesetzten Bedingungen müssen gleichzeitig zutreffen.

TextSourceConfig¶

TextSourceMode¶

Besonderheit:

• wenn title fehlt oder leer bleibt, rendert die App keinen Titeltext
• Dialoge für Slider, Select, Rollladen und Bestätigungen fallen intern auf die Widget-ID zurück, wenn kein Titel aufgelöst werden kann
• bei table sind führende oder abschliessende | optional; Markdown-Trennzeilen wie |---|---| werden ignoriert

WidgetImageConfig¶

WidgetImageScale¶

WidgetOverlayActionConfig¶

Wichtige Laufzeitregeln:

• icon ist Pflicht; fehlt es, gilt das Widget als fehlerhaft
• action verwendet dieselbe Struktur wie widgets[].action
• content.onWidgetActions funktioniert bei allen Widget-Arten
• bei Bild-Widgets erscheinen Overlay-Aktionen im selben Bereich wie Download und Vergrößern
• bestehende Konfigurationen mit image.onWidgetActions werden aus Kompatibilitätsgründen weiterhin gelesen

Kompatibilität bei WidgetImageConfig:

• image.onWidgetActions wird weiterhin unterstützt
• für neue Konfigurationen sollte stattdessen content.onWidgetActions verwendet werden

WidgetChartConfig¶

Grundidee:

• jede Serie bringt ihr eigenes datasetPath mit
• das Diagramm muss also kein gemeinsames Dataset verwenden
• die App vereint alle Serien auf eine gemeinsame X-/Y-Domain
• V1 interpoliert fehlende Punkte nicht und rendert bewusst schlank per Canvas

WidgetChartXAxisConfig¶

WidgetChartYAxisConfig¶

WidgetChartStyleConfig¶

WidgetChartSeriesConfig¶

WidgetChartValueSourceConfig¶

WidgetThermometerConfig¶

Laufzeitverhalten:

• das Widget rendert oben max und unten min als kleine Skalenlabels
• der Fuellstand in der Roehre wird aus valuePath auf den Bereich min..max geclamped
• der Werttext sitzt rechts neben der Roehre auf der passenden Hoehe
• wenn content.value fehlt, zeigt der Marker den numerisch formatierten Rohwert aus valuePath
• gradientColors erwartet mindestens zwei Farben; ungueltige oder zu kurze Listen fallen auf den Standardverlauf zurueck

WidgetGaugeConfig¶

Laufzeitverhalten:

• das Widget rendert eine halbkreisförmige Gauge mit Markerpunkt
• links und rechts erscheinen min und max als kleine Labels
• der Werttext sitzt mittig in der Öffnung des Gauge-Bogens
• wenn content.value fehlt, zeigt die Mitte den numerisch formatierten Rohwert aus valuePath
• gradientColors erwartet mindestens zwei Farben; ungueltige oder zu kurze Listen fallen auf den Standardverlauf zurück

ChartAxisValueKind¶

WidgetChartLineStyle¶

Typabhängige Pflichtfelder¶

Hinweis zum Rollladen-Schema:

• auch bei shutter ohne status bleibt content.shutter.valuePath im aktuellen Schema ein Pflichtfeld

Beispiel: Reiner Aktionsbutton ohne Status¶

{
  "id": "hot-water-boost",
  "content": {
    "mode": "icon_text",
    "icon": {
      "name": "water",
      "defaultColor": "#0E7490"
    },
    "title": {
      "mode": "static",
      "value": "Warmwasser jetzt"
    }
  },
  "action": {
    "request": {
      "url": "http://192.168.1.20/api/hot-water/boost-now"
    },
    "prompt": true
  }
}

Beispiel: Multi-Serien-Chart mit getrennten Datensätzen¶

{
  "id": "energy-history",
  "layout": {
    "order": 28,
    "size": "3/2"
  },
  "content": {
    "mode": "chart",
    "icon": {
      "name": "bolt",
      "defaultColor": "#C96C1A"
    },
    "title": {
      "mode": "static",
      "value": "Energiefluss heute"
    },
    "value": {
      "mode": "static",
      "value": "PV, Haus und Batterie"
    },
    "chart": {
      "xAxis": {
        "kind": "time"
      },
      "yAxis": {
        "unit": "W",
        "zeroLine": true
      },
      "series": [
        {
          "id": "pv",
          "label": "PV",
          "datasetPath": "pv.history",
          "x": { "valuePath": "timestamp" },
          "y": { "valuePath": "watts" },
          "color": "#E8B400"
        },
        {
          "id": "house",
          "label": "Haus",
          "datasetPath": "house.history",
          "x": { "valuePath": "time" },
          "y": { "valuePath": "watts" },
          "color": "#2563EB"
        },
        {
          "id": "battery",
          "label": "Batterie",
          "datasetPath": "battery.points",
          "x": { "valuePath": "ts" },
          "y": { "valuePath": "value" },
          "color": "#059669",
          "lineStyle": "dashed"
        }
      ]
    }
  },
  "status": {
    "request": {
      "url": "https://example.org/api/energy/history"
    }
  }
}

Beispiel: Thermometer mit eigenem Farbverlauf¶

{
  "id": "outside-temperature",
  "layout": {
    "order": 22,
    "size": "2/2"
  },
  "content": {
    "mode": "thermometer",
    "icon": {
      "name": "device_thermostat",
      "defaultColor": "#2563EB"
    },
    "title": {
      "mode": "static",
      "value": "Aussentemperatur"
    },
    "value": {
      "mode": "template",
      "value": "{{weather.outdoor.temperature}} °C"
    },
    "thermometer": {
      "min": -20,
      "max": 40,
      "valuePath": "weather.outdoor.temperature",
      "gradientColors": [
        "#2563EB",
        "#14B8A6",
        "#F97316",
        "#DC2626"
      ]
    }
  },
  "status": {
    "request": {
      "url": "https://example.org/api/weather/current"
    }
  }
}

Beispiel: Gauge mit Batteriestatus¶

{
  "id": "battery-charge",
  "layout": {
    "order": 29,
    "size": "2/2"
  },
  "content": {
    "mode": "gauge",
    "icon": {
      "name": "bolt",
      "defaultColor": "#0F766E"
    },
    "title": {
      "mode": "static",
      "value": "Batterie"
    },
    "value": {
      "mode": "template",
      "value": "{{battery.soc}} %"
    },
    "gauge": {
      "min": 0,
      "max": 100,
      "valuePath": "battery.soc",
      "gradientColors": [
        "#DC2626",
        "#F59E0B",
        "#16A34A"
      ]
    }
  },
  "status": {
    "request": {
      "url": "https://example.org/api/energy/storage"
    }
  }
}

Beispiel¶

{
  "id": "power-overview",
  "layout": {
    "order": 30,
    "size": "3/1"
  },
  "content": {
    "mode": "icon_text",
    "icon": {
      "name": "bolt",
      "namePath": "grid.icon_name",
      "defaultColor": "#C96C1A",
      "colorRules": [
        {
          "when": {
            "path": "grid.draw_watts",
            "greaterThan": 0.0
          },
          "color": "#D9485F"
        }
      ]
    },
    "title": {
      "mode": "static",
      "value": "Leistungsübersicht"
    },
    "value": {
      "mode": "table",
      "value": "Quelle | Leistung\nNetz | {{grid.draw_watts}} W\nPV | {{pv.watts}} W"
    },
    "colors": {
      "tileColor": "#1E293B",
      "titleColor": "#E2E8F0",
      "valueColor": "#F8FAFC",
      "tileColorRules": [
        {
          "when": {
            "path": "grid.draw_watts",
            "greaterThan": 0.0
          },
          "color": "#FFF4D8"
        }
      ],
      "titleColorRules": [
        {
          "when": {
            "path": "grid.draw_watts",
            "greaterThan": 0.0
          },
          "color": "#4A3412"
        }
      ],
      "valueColorRules": [
        {
          "when": {
            "path": "grid.draw_watts",
            "greaterThan": 0.0
          },
          "color": "#B45309"
        }
      ]
    },
    "typography": {
      "titleSizeSp": 18,
      "valueSizeSp": 22
    }
  },
  "status": {
    "request": {
      "url": "https://example.org/api/energy/current"
    }
  }
}

Weiterführend¶

• Icon und Text
• Chart
• Thermometer
• Gauge
• Bild
• Slider
• Select
• Rollladen