Widgets konfigurieren

Der Widget-Katalog liefert zu jedem Widget ein vollständiges JSON-Schema seiner Konfiguration: jedes Feld mit Überschrift und Erklärung, die Pflichtfelder benannt und mindestens eine fertige Beispiel-Konfiguration. Wer eine Szene ohne den Editor baut, liest daraus die Regeln, statt sie zu raten — und prüft seine Konfiguration dagegen, bevor er sie schreibt.

Den Katalog abrufen#

curl -sS "$SZENERA_API/v1/widget-catalog" \
  -H "Authorization: Bearer $TOKEN" | jq '.entries | length'

Die Antwort trägt unter entries je Widget einen Eintrag:

Der Katalog spiegelt den jeweils neuesten freigegebenen Stand einer App. Eine Organisation, die eine ältere Fassung installiert hat, kann geringfügig davon abweichen; maßgeblich ist dann die Fassung, die in appVersionPin der Instanz steht.

Was im configSchema steht#

Das configSchema ist ein JSON-Schema-Dokument nach Draft 2020-12. Es beschreibt genau das Objekt, das später als config in der Widget-Instanz steht.

Jeder Knoten unter properties trägt Klartext und, wo es sie gibt, die Grenzen des Werts:

Ein Ausschnitt aus dem Baustein „Text“:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "title": "Text",
  "description": "Statischer Text-Block mit voller Kontrolle über Schrift, Ausrichtung und Farben.",
  "properties": {
    "content": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "title": "Text",
      "description": "Der angezeigte Text. Zeilenumbrüche bleiben erhalten; Markup gibt es hier nicht."
    },
    "textAlign": {
      "type": "string",
      "enum": ["left", "center", "right"],
      "default": "center",
      "title": "Ausrichtung",
      "description": "Waagerechte Ausrichtung des Textes."
    }
  },
  "required": ["content"],
  "examples": [{ "content": "Ihr Text", "textAlign": "center", "fontSizeRem": 2 }]
}

Vier Regeln, die man dem Schema nicht ansieht#

• Pflicht heißt: es gibt keine Vorgabe. In required steht nur, was die Plattform nicht selbst einsetzen kann — meistens der Inhalt. Alles andere trägt ein default, und ein weggelassenes Feld nimmt genau diesen Wert an.
• Unbekannte Felder werden verworfen, nicht abgelehnt. Ein Feld, das das Schema nicht kennt, macht eine Konfiguration nicht ungültig; es verschwindet beim Speichern. Das hält Szenen lesbar, die vor einem Feld-Umbau entstanden sind — verlässt sich aber niemand darauf, dass ein Tippfehler auffällt.
• Die Beispiele sind vollständig und geprüft. Jeder Eintrag in examples ist eine Konfiguration, die das Schema erfüllt: die Start-Konfiguration und je Vorschau-Variante eine weitere. Der Bau einer App bricht ab, wenn ein Beispiel seine eigene Regel bricht.
• Eine Konfiguration überlebt neue Fassungen. Eine App fügt Felder nur mit Vorgabe hinzu, und keines verschwindet oder ändert seinen Typ. Eine gespeicherte Konfiguration bleibt deshalb gültig, wenn die Organisation die App aktualisiert, und eine ältere Fassung, die ein Display noch spielt, liest auch eine Konfiguration mit Feldern einer neueren.

Zwei Werte mit fester Form: Ort und Fläche#

Zwei Feldarten der Editor-Formulare schreiben Werte, deren Form überall gleich ist. Wer eine Konfiguration selbst baut, findet sie im configSchema als Objekt bzw. Zeichenkette wieder:

Wie der Editor diese und alle anderen Felder zeigt, gliedert und an die Leiste am Widget stellt, beschreibt die Formular-Beschreibung der App (config-ui.ts, Typ WidgetConfigUI). Sie gehört zum Editor, nicht zum Katalog: Das configSchema bleibt die eine Regel für jeden, der eine Konfiguration schreibt.

Die sechs eingebauten Bausteine#

Text, Bild, Video, Form, Grafik und Dokument gehören zur Grundausstattung: Sie werden nicht installiert, brauchen keine Zustimmung und stehen jeder Organisation offen. Im Katalog erscheinen sie wie die Widgets einer App — mit der reservierten Kennung core und dem festen Versions-Pin 0.0.0.

Bild, Video und Dokument verweisen auf die Medienbibliothek statt auf eine Adresse: assetRef trägt die Kennung der Datei und die Fassungen, die die Anzeige braucht. Ohne assetRef zeigt das Widget einen gestalteten Platzhalter — das ist ein gültiger Zustand und kein Fehler.

Beim Dokument bleibt assetRef.variantSet leer: Seine Seitenbilder reisen immer mit, je Seite eine Zeile page-<n> in der Medien-Liste des Snapshots. Welche Seiten das Widget zeigt, steht in pages: numbers sind die gewählten Seiten, of die Seitenzahl der Datei beim Wählen. Fehlt pages, zeigt das Widget alle Seiten außer leeren. Hat die Datei später eine andere Seitenzahl als of, meldet die Prüfung der Szene DocumentPagesChanged (ein Hinweis, kein Halt). Das Dokument erklärt drei Vorlagen (page, spread, full) und die Mindestgröße 200 × 200.

Je Baustein eine fertige Widget-Instanz#

So sieht ein Eintrag in document.widgets einer Szene aus. id ist eine neue Kennung im Format wgi_<ULID>, frame die Box in Pixeln der Szenenfläche, zIndex die Stapelreihenfolge.

Text

{
  "id": "wgi_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "appId": "core",
  "widgetType": "text",
  "appVersionPin": "0.0.0",
  "frame": { "x": 120, "y": 120, "w": 1680, "h": 400 },
  "zIndex": 10,
  "config": {
    "content": "Willkommen in Ihrer Apotheke",
    "fontFamily": "inter",
    "fontStyle": "sans",
    "fontWeight": "bold",
    "fontSizeRem": 3,
    "lineHeight": "tight",
    "textTransform": "none",
    "textAlign": "center",
    "verticalAlign": "middle",
    "padding": "md",
    "textColor": "#0f172a",
    "backgroundStyle": "transparent",
    "backgroundColor": "#ffffff"
  }
}

Bild

{
  "id": "wgi_01ARZ3NDEKTSV4RRFFQ69G5FAW",
  "appId": "core",
  "widgetType": "image",
  "appVersionPin": "0.0.0",
  "frame": { "x": 0, "y": 0, "w": 1920, "h": 1080 },
  "zIndex": 0,
  "config": {
    "assetRef": { "assetId": "ast_01ARZ3NDEKTSV4RRFFQ69G5FAV", "variantSet": ["webp", "original"] },
    "fit": "cover",
    "position": { "x": "center", "y": "center" },
    "borderRadius": "none",
    "backgroundMode": "color",
    "backgroundColor": "#0f172a",
    "motionEffect": "kenburns",
    "kenBurns": { "zoom": 1.15, "durationSec": 24, "direction": "in" }
  }
}

Video

{
  "id": "wgi_01ARZ3NDEKTSV4RRFFQ69G5FAX",
  "appId": "core",
  "widgetType": "video",
  "appVersionPin": "0.0.0",
  "frame": { "x": 0, "y": 0, "w": 1920, "h": 1080 },
  "zIndex": 0,
  "config": {
    "assetRef": { "assetId": "ast_01ARZ3NDEKTSV4RRFFQ69G5FAV", "variantSet": ["original"] },
    "loop": true,
    "muted": true,
    "autoplay": true,
    "fit": "cover",
    "position": { "x": "center", "y": "center" },
    "borderRadius": "none",
    "backgroundMode": "color",
    "backgroundColor": "#000000",
    "startAtSeconds": 0
  }
}

Form

{
  "id": "wgi_01ARZ3NDEKTSV4RRFFQ69G5FAY",
  "appId": "core",
  "widgetType": "shape",
  "appVersionPin": "0.0.0",
  "frame": { "x": 120, "y": 560, "w": 480, "h": 80 },
  "zIndex": 5,
  "config": {
    "variant": "rectangle",
    "fillColor": "#0f766e",
    "fillTransparent": false,
    "fillOpacity": 1,
    "strokeColor": "#0f172a",
    "strokeWidth": 0,
    "cornerRadius": 0,
    "innerRadius": 60,
    "pointDepth": 60,
    "headSize": 36,
    "shaftWidth": 28,
    "lineCap": "butt",
    "dash": "none",
    "rotationDeg": 0
  }
}

Grafik

{
  "id": "wgi_01ARZ3NDEKTSV4RRFFQ69G5FAZ",
  "appId": "core",
  "widgetType": "graphic",
  "appVersionPin": "0.0.0",
  "frame": { "x": 1500, "y": 760, "w": 320, "h": 320 },
  "zIndex": 20,
  "config": {
    "graphicId": "pfeil-rechts",
    "tintColor": "#0f172a",
    "accentColor": "#0f766e",
    "flipH": false,
    "flipV": false,
    "opacity": 1
  }
}

Dokument

{
  "id": "wgi_01ARZ3NDEKTSV4RRFFQ69G5FB0",
  "appId": "core",
  "widgetType": "document",
  "appVersionPin": "0.0.0",
  "frame": { "x": 0, "y": 0, "w": 1920, "h": 1080 },
  "zIndex": 0,
  "config": {
    "assetRef": { "assetId": "ast_01ARZ3NDEKTSV4RRFFQ69G5FAV", "variantSet": [] },
    "pages": { "numbers": [1, 2, 3], "of": 3 },
    "display": "sequence",
    "fit": "page",
    "interval": 10,
    "corners": "round",
    "surface": "dark"
  }
}

Kürzer geht es auch: Weil jedes Feld außer content eine Vorgabe trägt, ist { "content": "Willkommen" } bereits eine gültige Text-Konfiguration. Die ausgeschriebene Fassung oben ist die, die der Editor speichert.

Eine Konfiguration prüfen, bevor Sie sie schreiben#

Nehmen Sie das configSchema des gewünschten Widgets und geben Sie es einem Prüfer für Draft 2020-12. Der Ertrag ist eine feldgenaue Meldung, statt einer abgelehnten Anfrage.

import Ajv2020 from 'ajv/dist/2020.js';

const katalog = await (await fetch(`${api}/v1/widget-catalog`, { headers })).json();
const eintrag = katalog.entries.find(
  (e) => e.appId === 'core' && e.definition.id === 'text',
);

const pruefe = new Ajv2020({ allErrors: true }).compile(eintrag.definition.configSchema);
const config = { content: 'Willkommen in Ihrer Apotheke', fontSizeRem: 3 };

if (!pruefe(config)) {
  for (const fehler of pruefe.errors) {
    console.error(`${fehler.instancePath || '(Wurzel)'}: ${fehler.message}`);
  }
}

Drei Dinge nimmt Ihnen der Prüfer nicht ab:

• Ob es die Datei gibt, auf die assetRef zeigt. Das beantwortet die Medienbibliothek.
• Ob der Widget-Typ zu einer installierten App gehört. Widgets einer nicht installierten App weist die Plattform beim Veröffentlichen ab; die eingebauten Bausteine stehen immer offen.
• Ob die Konfiguration Sinn ergibt. Ein QR-Code mit leerer Adresse ist schema-gültig und zeigt trotzdem nur einen Platzhalter.

Das Formular im Editor#

Dieser Abschnitt richtet sich an App-Autoren: Er beschreibt, wie der Szenen-Editor aus der Formular-Beschreibung einer App (config-ui.ts) das Einstellungs-Fenster und die Leiste am Widget baut. Für eine Konfiguration über die Schnittstelle ändert er nichts.

Die Rangfolge#

Das Einstellungs-Fenster nimmt die Formular-Beschreibung der App, wenn sie eine hinterlegt (registry.registerConfigUI(widgetType, ui)). Nur ohne sie greift ein eigenes Formular der App (registerConfigForm), ohne beides ein aus dem Schema abgeleitetes. Deklarativ zuerst, damit gemeinsame Verbesserungen (Gliederung, eingeklappte Gruppen, Hinweise, Ort-Feld) jede App erreichen, ohne dass sie ihr Formular nachzieht. Eine App im neuen Standard registriert deshalb kein ganzes Formular mehr, sondern höchstens einzelne Felder.

Eigene Felder: registerConfigField#

Was keine Feldart abbildet (eine Stadtsuche, eine Auswahl aus eigenen Daten), bringt die App als einzelnes Bedienelement mit:

import type { AuthoringRegistry, ConfigFieldProps } from '@szenera/widget-editor/registry';
import type { GeoPlace } from '@szenera/apps-sdk/config';

function CityPicker({ value, onChange, apiFetch, context }: ConfigFieldProps<GeoPlace | null>) {
  // sucht über apiFetch die Städte der App, context.locale für die Schreibweise
}

export function registerAuthoring(registry: AuthoringRegistry): void {
  registry.registerConfigUI('weather', weatherConfigUI);
  registry.registerConfigField('weather', 'location.place', CityPicker as never);
}

Der Schlüssel ist der Punkt-Pfad des Felds (city) oder eines Teils davon (location.place ist die Ortsauswahl des Ort-Felds location). Das Formular rendert Beschriftung, Hilfetext, Pflicht-Stern und Fehler um das Bedienelement herum. Es bekommt:

Feldarten mit eigenem Bedienelement#

Schnellfelder: quickFields#

Höchstens zwei Felder kompakter Art (color, segmented, select, slider, toggle, surface) nennt quickFields, in der Reihenfolge der Leiste. Andere Arten und mehr als zwei Felder lässt die Leiste weg, defineWidgetConfigUI() meldet das schon beim Bau. Neben den Schnellfeldern zeigt die Leiste bei einem Widget mit mehreren Vorlagen die Vorlagen-Auswahl (Widget, Konfiguration und Vorschau).

Der Passt-Bericht: Schlüssel sind Feldnamen#

Blendet die Laufzeit einen eingeschalteten Inhalt aus, weil der Rahmen zu klein ist, meldet sie ihn mit useFitReport().reportHidden(parts). Die Teile heißen wie die Felder der Config, die den Inhalt einschalten, etwa ['showDaily']. Der Editor zeigt dann unter der Vorschau „In diesem Rahmen ausgeblendet: Nächste Tage.“ mit der Beschriftung des Felds aus der Formular-Beschreibung und unter dem Schalter einen Satz, warum er nichts bewirkt. Ein Teil ohne passendes Feld erscheint mit seinem Schlüssel.

Weiterführendes#

• Widget, Konfiguration und Vorschau — wie eine App ihre Widget-Definition schreibt, aus der dieses Schema entsteht.
• Signieren und der Weg in den Katalog — die beiden Kataloge über alle Apps und ihre Abfragen.
• Datenzugriff, Rechte und Bedingungen — was eine App vor der Installation offenlegt.