Foundries

Foundries sind wiederverwendbare Forge-Vorlagen. Eine Foundry beschreibt ein Muster aus forge, element, uix, Makros und Billets. Einzelne Forge-Instanzen können diese Vorlage verwenden und gezielt Werte überschreiben.

Ab UIX 9.0.0-beta.0 kann eine Foundry zusätzlich element_base bereitstellen. Diese elementeigene Basis und das Forge-Overlay element werden unabhängig aufgelöst. Enthält die aufgelöste Konfiguration element_base, aktiviert sie die geschichtete Konfiguration. Diese Vorschau gehört nicht zur stabilen Version 8.4.0.

Global Foundries

Global Foundries stehen dashboardweit zur Verfügung. Sie eignen sich für wiederkehrende Kacheln, Standardstile, Lock-Muster, Badge-Layouts oder Kombinationen aus Sparks.

Foundries verwalten

UI Foundries

UI Foundries werden in der Home-Assistant-Oberfläche gepflegt. Sie sind bequem für kleinere Vorlagen und schnelle Anpassungen.

YAML File Foundries

YAML File Foundries liegen in Dateien und sind besser für größere oder versionierte Konfigurationen geeignet.

Dateiformat

foundries:
  living_room_tile:
    forge:
      mold: card
    element:
      type: tile
      entity: "{{ entity }}"
    billets:
      entity: light.living_room

YAML-Anker

YAML-Anker können gemeinsame Teile wiederverwenden.

defaults: &tile_defaults
  forge:
    mold: card
  element:
    type: tile

foundries:
  light_tile:
    <<: *tile_defaults
    billets:
      entity: light.living_room

YAML-Merge-Keys sind flach

YAML-Merge-Keys mergen nur die aktuelle Ebene. Verschachtelte Maps werden nicht tief zusammengeführt. Für tiefe Kombinationen nutze lieber Foundry-Merge-Verhalten.

Datei registrieren

Eine YAML-Datei muss in UIX registriert werden, damit ihre Foundries geladen werden. Der genaue Ort hängt von deiner Home-Assistant-Konfiguration ab, typisch ist ein Pfad unter /config/uix/.

Dateien neu laden

Nach Änderungen an YAML-Dateien müssen die Foundries neu geladen werden. Danach greifen neue Forge-Instanzen auf die aktualisierte Vorlage zu.

Registrierung entfernen

Nicht mehr benötigte Dateien können aus der Foundry-Registrierung entfernt werden. Bereits konfigurierte Dashboards sollten danach keine Foundries aus dieser Datei mehr referenzieren.

Vorrang

Wenn Foundries denselben Namen verwenden, entscheidet die UIX-Ladereihenfolge. Halte Namen eindeutig, damit keine unbeabsichtigte Vorlage eine andere überschreibt.

Foundry verwenden

type: custom:uix-forge
forge:
  foundry: living_room_tile

Mit Überschreibung:

type: custom:uix-forge
forge:
  foundry: living_room_tile
  billets:
    entity: light.kitchen

Struktur einer Foundry-Konfiguration

Eine Foundry kann foundry, forge, element und ab UIX 9.0.0-beta.0 element_base enthalten. element_disabled_paths ist ausschließlich lokal an der nutzenden Forge-Instanz erlaubt, auch nicht in global oder global_<mold>.

foundries:
  my_foundry:
    forge:
      mold: card
      sparks: []
    element:
      type: tile
      entity: "{{ entity }}"
    uix:
      style: |
        ha-card {
          border: 1px solid var(--primary-color);
        }
    macros: {}
    billets:
      entity: light.living_room

Externe Dateien und Secrets einbinden

Quotes in UI Foundries erforderlich

In UI Foundries müssen !include und !secret als String gequotet werden. In YAML File Foundries können sie als YAML-Tags geschrieben werden.

!include

# /config/uix/my_forge_styles.yaml
style: |
  ha-card {
    border-radius: 12px;
  }

# In einer YAML File Foundry - keine Quotes noetig
uix: !include /config/uix/my_forge_styles.yaml

# In einer UI Foundry - Quotes erforderlich
uix: "!include /config/uix/my_forge_styles.yaml"

!secret

# /config/secrets.yaml
my_pin: 1234

# In einer YAML File Foundry - keine Quotes noetig
pin: !secret my_pin

# In einer UI Foundry - Quotes erforderlich
pin: "!secret my_pin"

Merge-Verhalten

Foundry-Konfigurationen werden mit der Instanzkonfiguration zusammengeführt. Dadurch kannst du Defaults in der Foundry definieren und nur die abweichenden Werte im Dashboard setzen.

Die Reihenfolge lautet global → global_<mold> → geerbte Foundries → benannte Foundry → lokale Konfiguration. Mappings wie forge, element und element_base werden rekursiv zusammengeführt; Arrays und Skalare werden ersetzt. element_base und element bleiben während der Foundry-Auflösung getrennt und werden erst danach als Schichten zusammengesetzt. Lokale element_disabled_paths greifen auf das aufgelöste Overlay zu.

Merge-Beispiel

Foundry:

foundries:
  base_tile:
    forge:
      mold: card
      sparks:
        - type: tooltip
          content: "{{ tooltip }}"
    element:
      type: tile
      entity: "{{ entity }}"
    billets:
      tooltip: Details anzeigen

Instanz:

type: custom:uix-forge
forge:
  foundry: base_tile
  billets:
    entity: light.kitchen
    tooltip: Kuechenlicht

Ergebnisgedanke:

forge:
  mold: card
  sparks:
    - type: tooltip
      content: Kuechenlicht
element:
  type: tile
  entity: light.kitchen

Verschachtelte Foundries

Foundries können auf anderen Foundries aufbauen.

foundries:
  base_tile:
    forge:
      mold: card
    element:
      type: tile

foundries:
  locked_tile:
    forge:
      foundry: base_tile
      sparks:
        - type: lock
          locks:
            - pin: 1234

type: custom:uix-forge
forge:
  foundry: locked_tile
element:
  entity: light.living_room

Zirkuläre Referenzen

Foundries dürfen sich nicht gegenseitig endlos referenzieren. Achte darauf, dass die Kette eindeutig endet.

Billets in Foundries

Billets sind der wichtigste Weg, um Foundries flexibel zu halten.

Muster 1: Defaults in der Foundry definieren, pro Instanz überschreiben

foundries:
  room_tile:
    billets:
      entity: light.living_room
      name: Wohnzimmer
    element:
      type: tile
      entity: "{{ entity }}"
      name: "{{ name }}"

type: custom:uix-forge
forge:
  foundry: room_tile
  billets:
    entity: light.kitchen
    name: Kueche

element:
  type: tile
  entity: light.kitchen
  name: Kueche

Muster 2: Leere Billet-Slots in der Foundry definieren

foundries:
  required_entity_tile:
    billets:
      entity: ~
    element:
      type: tile
      entity: "{{ entity }}"

type: custom:uix-forge
forge:
  foundry: required_entity_tile
  billets:
    entity: sensor.outdoor_temperature

element:
  type: tile
  entity: sensor.outdoor_temperature

::: note UI Foundries: Kommentare werden entfernt In UI Foundries bleiben YAML-Kommentare nicht erhalten. Wenn Kommentare wichtig sind, nutze eine YAML-Datei im Repository.

:::

UIX-Styling aus einer Foundry

Foundries können eigene uix-Styles enthalten. Die Instanz kann diese Styles ergänzen.

Styles kombinieren

Lege gemeinsame Struktur und Theme-Variablen in die Foundry und instanzspezifische Abweichungen direkt in die Forge-Instanz.

# Foundry: "styled_tile"
foundries:
  styled_tile:
    forge:
      mold: card
    element:
      type: tile
      entity: "{{ entity }}"
    uix:
      style: |
        ha-card {
          border: 1px solid var(--primary-color);
        }

# Forge - fuegt eigenes UIX-Styling hinzu
type: custom:uix-forge
forge:
  foundry: styled_tile
  billets:
    entity: light.living_room
uix:
  style: |
    ha-card {
      box-shadow: var(--ha-card-box-shadow);
    }

Beispiel: Global Foundry mit Makro

TIP

Makros in Foundries halten wiederkehrende Template-Logik an einer Stelle.

foundries:
  state_colored_tile:
    macros:
      active_color: |
        {% macro active_color(entity) -%}
        {{ 'var(--success-color)' if is_state(entity, 'on') else 'var(--disabled-color)' }}
        {%- endmacro %}
    billets:
      entity: light.living_room
    forge:
      mold: card
    element:
      type: tile
      entity: "{{ entity }}"
    uix:
      style: |
        ha-card {
          border-color: {{ active_color(entity) }};
        }

type: custom:uix-forge
forge:
  foundry: state_colored_tile
  billets:
    entity: light.kitchen