Elementvorlagen und Hilfsfunktionen

Diese Referenz beschreibt die derzeit vom List-Baustein verwendete Vorlagensprache. Die allgemeine Map-Konfiguration steht unter Wertzuordnungen; vollständige Konfigurationen enthalten die Listenbeispiele.

Bearbeiten und Vorschau

Öffne Eintragslayout, um den HTML-/Handlebars-Quelltext eines Listeneintrags zu bearbeiten. Vorlagenausgaben einer Wertzuordnung verwenden denselben Editor im Text- oder HTML-Modus.

Aktion	Wirkung
Formatieren	Rückt gültigen Quelltext ein. Bei leerem oder syntaktisch ungültigem Quelltext nicht verfügbar.
Zeilen umbrechen	Ändert die Editoransicht, fügt aber keine Zeilenumbrüche in den Quelltext ein.
Vergrößern-Schaltfläche	Vergrößert den Editor für längere Vorlagen.
Strg+F	Sucht im Quelltext.
Tab	Rückt innerhalb des Editors ein. Esc, danach Tab, verlässt ihn.
Strg+Z	Macht Eingaben, eingefügte Beispiele und Formatierung rückgängig.

Abbrechen oder ein Wechsel der bearbeiteten Vorlage/des Bausteins setzt die Editorhistorie zurück. Rückgängig stellt damit keinen Quelltext eines anderen Dokuments wieder her. Ein anderer Vorschaueintrag verändert weder Quelltext und Feldauswahl noch echte Listendaten.

Das Ereignisbeispiel im aktuellen Eintragseditor, einschließlich abgesicherter Zeilenklasse und ausdrücklich gerendertem Map-Fragment.

Vorlagenhilfe

Die aufklappbare Vorlagenhilfe enthält sechs Gruppen:

Gruppe	Beispiele
Felder	Maskiertes Feld, Ersatztext bei leerem Feld, rohes HTML, ganzer Eintrag, JSON und ein Feld mit dem Namen einer Hilfsfunktion.
Formatierung	Zahlen und Datumswerte.
Bedingungen und Schleifen	If/else, Zahlenschwelle, verschachtelte Liste mit Trennzeichen/Leertext und verschachteltes Objekt mit with.
Symbole und Bilder	Symbolschrift, Bibliothekssymbol und Asset.
Wertzuordnungen	Rohwertabruf und ausdrückliches Rendern eines Vorlagenfragments.
Zeilenlayout	Ein konfigurierbares Beispiel für äußere Zeilenklassen und ein Symbol neben zwei Textzeilen.

Jedes Beispiel enthält Einstellungen, erzeugten Code und eine gerenderte Vorschau. Einfügen ersetzt die Editorauswahl an der Cursorposition; Kopieren kopiert den Quelltext. Beide Aktionen fügen keine Vorschaudaten ein.

Feldvorschläge stammen aus passenden Werten des ersten Listeneintrags. Eintrag für Vorschau ändert den zum Rendern verwendeten Eintrag, ohne die gewählten Feldpfade neu zu erzeugen. Ein im ersten Eintrag vorgeschlagenes Feld kann in einem anderen fehlen; damit lässt sich das Ersatzverhalten prüfen.

Fehlen geeignete echte Daten, zeigen Feld-, Listen- und Objektbeispiele gekennzeichnete Beispieldaten. Ihr Code löst weiterhin ein Feld auf oder führt die gezeigte Hilfsfunktion aus. Beispielsweise enthält das Beispiel für maskierte Felder ein Message-Feld mit Markup; der Quelltext bleibt {{this.Message}}, und das Markup erscheint als Text. Das Beispiel für rohes HTML rendert bewusst Markup. Beim leeren Feld enthält der Beispieldatensatz tatsächlich einen leeren Wert, sodass der Ersatzzweig ausgeführt wird.

Beispieldaten gelten nur für die jeweilige Vorschau. Das Einfügen des Quelltexts ergänzt keine Message-, Items- oder Details-Felder in echten Einträgen. Passe solche Feldpfade vor der Verwendung an dein tatsächliches Schema an.

Feste Assets müssen über Asset auswählen tatsächlich ausgewählt werden. Ein Bibliothekssymbol-Beispiel ohne passenden Laufzeitschlüssel wartet auf eine ausdrückliche Schlüsseleingabe oder Auswahl. Es wird kein installiertes Asset oder Bibliothekssymbol vorausgesetzt. Für noch nicht verfügbare Ausschnitte bleiben Kopieren/Einfügen deaktiviert. Map-Eingaben/-Ausgaben werden pro Map beibehalten und gegen deren aktuelle Definitionen sowie passende Ausgabetypen geprüft.

Ohne passende echte Einträge löst das Feldbeispiel Message aus gekennzeichneten Beispieldaten auf. Eingefügt oder kopiert wird ausschließlich der angezeigte Vorlagenquelltext.

Kontext und Feldzugriff

Ausdruck	Bedeutung
{{this}}	Aktueller Eintrag oder aktueller verschachtelter Kontext.
{{this.Message}}	Message-Feld des aktuellen Objekts.
{{this.Details.Message}}	Verschachteltes Feld.
{{lookup this "display name"}}	Feld mit einem zu zitierenden Schlüssel.
{{@root.Message}}	Message des ursprünglichen obersten Eintrags, auch in Schleifen/Fragmenten.
{{../Name}}	Name im übergeordneten Handlebars-Kontext.
{{@index}} / {{@key}}	Aktueller Schleifenindex/-schlüssel in each.

Feldnamen sind groß-/kleinschreibungsabhängig. Ein fehlendes Feld ergibt leeren Text. Hilfsfunktionen haben Vorrang vor gleichnamigen Feldern: Verwende {{this.icon}} statt {{icon}} für ein Feld namens icon. Dasselbe gilt für asset, map, row und andere Hilfsfunktionsnamen.

Gewöhnliche Handlebars-Ausdrücke führen kein beliebiges JavaScript aus. Verwende registrierte Hilfsfunktionen und Unterausdrücke wie {{number (map "Metrics" this.State "count") 0}}; die genannte Map/Ausgabe muss existieren.

HTML und Zeilenumbrüche

{{this.Message}} maskiert HTML-Zeichen. Enthält Message <strong>Ready</strong>, erscheint dieser Text wörtlich. {{{this.Message}}} fügt rohes HTML ein und zeigt Ready fett. Verwende rohe Ausgabe nur für Werte, die bewusst als vertrauenswürdiges Markup gedacht sind.

Direkt in der Vorlage geschriebenes HTML bleibt erhalten. Das Rendern ist keine allgemeine HTML-Bereinigung. Symbol-/Bildhelfer prüfen ihre eigenen Argumente und erzeugen eigenes Markup; beliebige Daten in dreifachen Klammern werden dadurch nicht sicher.

Zeilenumbrüche unmittelbar neben HTML-Tags werden zu Leerzeichen normalisiert, damit eingerückte HTML-Vorlagen möglich sind. Andere Quelltextumbrüche bleiben sichtbar, ebenso Umbrüche innerhalb eingefügter Werte. Zwei reine Feldausdrücke auf getrennten Zeilen erzeugen somit zwei Textzeilen. Handlebars-Leerraumsteuerung (~) kann unerwünschten Leerraum an Ausdrücken und Blöcken entfernen.

Formatierungshelfer

Syntax	Verhalten
{{number this.Temperature 1 locale="de-DE"}}	Formatiert eine endliche Zahl mit genau einer Nachkommastelle in der angegebenen Sprache/Region. Ohne Stellenargument gilt die normale lokale Formatierung. Numerische Zeichenketten werden hier nicht umgewandelt.
{{date this.Time "DD.MM.YYYY HH:mm:ss"}}	Formatiert eine ISO-Datumszeichenkette, Millisekunden seit Unix-Epoche oder einen Date-Wert mit denselben Moment-Formatzeichen wie die Uhr. Standard: L LTS. Ungültige/nicht unterstützte Daten ergeben leeren Text.
{{json this}}	JSON-Darstellung, einschließlich Anführungszeichen bei Zeichenketten. Gewöhnliches Einfügen maskiert das Ergebnis weiterhin für HTML. Undefined ergibt leeren Text.

Für Nicht-Zahlen oder nicht endliche Zahlen liefert number leeren Text. Verwende gültige Gebietsschemata und Stellenzahlen; ungültige Formatargumente können eine Rendering-Diagnose verursachen. Die Datumsanzeige folgt dem Zeitzonenverhalten der Rendering-Umgebung; eine UTC-Eingabe wird ohne entsprechende Konfiguration nicht zwingend in UTC angezeigt.

Bedingungen und Schleifen

if, unless, each, with und lookup sind Standardhelfer von Handlebars. eq und ne verwenden strikte Gleichheit/Ungleichheit. lt, lte, gt und gte verwenden die relationalen Vergleiche von JavaScript; halte die verglichenen Werte konsistent typisiert.

{{#if (gte this.Temperature 25)}}Warm{{else}}Normal{{/if}}

Temperature sollte hier eine Zahl sein. false, die Zahl 0 und leerer Text gelten in einem gewöhnlichen if als falsch; eine fehlende Ausgabe ebenfalls. Verwende einen ausdrücklichen eq-Vergleich, um false von nicht gesetzt zu unterscheiden. Mit includeZero=true kann eine vorhandene Zahl 0 berücksichtigt werden.

{{#each this.Tags}}
    {{#unless @first}}, {{/unless}}{{this}}
{{else}}
    No tags
{{/each}}

In each ist this ein Tag und nicht der ganze Eintrag. @root bezeichnet weiterhin den ursprünglichen Eintrag. Für ein optionales verschachteltes Objekt:

{{#with this.Details}}
    {{this.Message}}
{{else}}
    No details
{{/with}}

Das Beispiel für typisierte Ausgaben behandelt false, 0, leeren Text und fehlende Map-Werte.

Symbole und Bilder

Alle drei Helfer erzeugen Inline-Markup in der durch --list-icon-size bestimmten Größe, standardmäßig 1.2em. Argumente können feste Werte oder Eintrags-/Map-Felder sein.

Helfer	Quelle und Verhalten
{{icon "play circle outline" color="green"}}	Symbolschrift mit denselben Namen wie beim Symbol-Baustein.
{{poolIcon this.LibraryIcon}}	NeuroomNet-Bibliothekssymbol über seinen Schlüssel. Die lokale Bibliothek wird vor der Online-Bibliothek durchsucht. Bibliothekssymbole behalten ihre eigenen Farben.
{{asset this.ImageId}}	Bild aus der Asset-Bibliothek, aufgelöst über ID oder Titel.

Symbolnamen erlauben Kleinbuchstaben, Ziffern, Leerzeichen und Bindestriche. Benannte Farben sind red, orange, yellow, olive, green, teal, blue, violet, purple, pink, brown, grey und black. Hex sowie unterstützte rgb(...)-/hsl(...)-Formen sind ebenfalls möglich. Ungültige Namen ergeben kein Symbol; ungültige Farben werden ignoriert. Ein syntaktisch gültiger Name benötigt trotzdem ein Zeichen in der installierten Symbolschrift.

Nicht auflösbare Bibliothekssymbole und Assets ergeben kein Bild. Asset-IDs überstehen Titeländerungen, Titelreferenzen nicht. Bei mehreren Assets mit gleichem Titel wird das älteste verwendet. Eine über den Picker gewählte ID ist die stabilere Referenz.

Der Editor gibt hellen Symbolen einen Kontrastschatten in Vorschauen, damit sie sich vom Vorschauhintergrund abheben. Die konfigurierte Farbe bleibt erhalten. Prüfe ein scheinbar leeres helles Symbol auch vor dem tatsächlichen Dashboardhintergrund.

Ein nur im Quelltext oder in Eintragsdaten genanntes Asset wird nicht als in Verwendung erfasst. Speichere es für Löschschutz in einer deklarierten Asset-Referenz-Ausgabe; siehe Asset-Verwaltung.

Map-Rohwerte und Fragmente

Syntax	Ergebnis
{{map "StateAppearance" this.State "label"}}	Typisierter Rohwert. Eine Vorlagenausgabe liefert Quelltext, ohne ihn auszuführen.
{{renderMap "StateAppearance" this.State "content"}}	Rendert eine Text-/HTML-Vorlagenausgabe. Andere Ausgabetypen werden mit Diagnose abgelehnt.

Fehlende Maps, Schlüssel, Treffer oder nicht gesetzte Werte ergeben keine sichtbare Ausgabe. Ein fehlgeschlagener renderMap-Aufruf erzeugt zusätzlich eine Diagnose. map setzt keine Zeilenmetadaten. Schlüssel besitzen keine eingebaute Bedeutung: icon wird nicht automatisch als Symbol gerendert, class gestaltet nicht automatisch eine Zeile.

Fragmentkontext

Schlüsselwort	Wert im gerenderten Fragment
this	Aktueller Kontext des Aufrufers. In einem äußeren each kann das ein verschachteltes Objekt sein.
@root	Oberster Listeneintrag.
@value	Eingabe aus dem zweiten Argument dieses renderMap-Aufrufs.
@outputs	Rohwerte der ausgewählten Regel, einschließlich Vorlagenquelltext.

Schleifendaten und Asset-/Bibliotheksauflösung bleiben verfügbar. Ein verschachtelter Aufruf hat eigene @value-/@outputs-Werte; anschließend gelten wieder die des Elternaufrufs. Ungewöhnliche Schlüssel werden mit lookup gelesen, beispielsweise {{asset (lookup @outputs "image key")}}.

Andere Ausgaben werden nicht automatisch ausgeführt. {{@outputs.content}} fügt den Quelltext von content als Wert ein. Rufe für eine andere Vorlagenausgabe ausdrücklich renderMap mit Map-Name, Eingabe und Schlüssel auf. Siehe verschachtelte Fragmente.

Text- und HTML-Modus

HTML-Fragmente behalten selbst verfasstes Markup und maskieren gewöhnlich eingefügte Daten. Textfragmente erzeugen eine reine Zeichenkette ohne interne HTML-Maskierung; das normale Einfügen in die äußere HTML-Vorlage maskiert sie dann genau einmal. Ein Textfragment kann keine Zeilenmetadaten beitragen, auch nicht über darin verschachtelte HTML-Fragmente.

Dreifache Klammern umgehen ausdrücklich die normale äußere Maskierung. Verwende gewöhnliche doppelte Klammern für als Text gedachte Textfragmente. Die Modi betreffen das Rendern, nicht den Regelvergleich oder die Speicherung von Quelltextzeichenketten.

Klassen der äußeren Zeile

row deklariert Metadaten für den äußeren Listeneintrag, ohne sichtbares HTML auszugeben. Es ist unabhängig von Wertzuordnungen:

{{row class='event urgent'}}
{{this.Message}}

Der Eintrag erhält listItem-event und listItem-urgent. Tokens dürfen ASCII-Buchstaben, Ziffern, Unterstriche und Bindestriche enthalten; mehrere Tokens werden durch Leerraum getrennt. Leerer Text deklariert keine Klassen. Ungültige Deklarationen tragen keine Klassen bei und erzeugen eine Diagnose. Unterstützt wird ausschließlich das benannte Argument class, ohne Positionsargumente oder weitere Attribute.

Mehrfache Deklarationen werden pro Eintrag vereinigt und dedupliziert. {{row class="selected"}} erzeugt listItem-selected, nicht die eigene selected-Klasse des List-Bausteins, und wählt keinen Eintrag aus. Klassen werden bei Rendering-Änderungen neu berechnet, statt sich an einem DOM-Element anzusammeln.

HTML-Fragmente können Klassen zum Aufrufer beitragen, Textfragmente nicht. Schlägt ein Fragment nach einer Klassendeklaration fehl, verwirft es seinen begonnenen Klassenbeitrag. Andere erfolgreiche Deklarationen im Eintrag bleiben erhalten.

Sichere einen möglicherweise nicht gesetzten Map-Wert ab:

{{#with (map 'StateAppearance' this.State 'rowStyle')}}
    {{row class=this}}
{{/with}}

Alternativ kann rowStyle in jeder Regel ohne Klassen ausdrücklich leeren Text enthalten. Ein nicht gesetzter Wert direkt an row ist ungültig. CSS verwendet das erzeugte Präfix. Das Ereignisbeispiel verwendet einen Selektor, der Vorrang vor der Standardzeilengestaltung hat und die Auswahlhervorhebung erhält.

Der allgemeine row-Helfer deklariert listItem-event ohne sichtbaren Zeileninhalt. Ein Map-Abruf ist nicht erforderlich.

Ausgerichtete Inhalte

Das List-Stylesheet bietet Rezeptklassen für einen gleichbleibenden Symbolplatz neben dem Inhalt:

<div class='dashboardListControlRow'>
    <span class='dashboardListControlRowIcon'>{{icon this.Icon color=this.Color}}</span>
    <div class='dashboardListControlRowContent'>
        <div>{{date this.Time 'DD.MM.YYYY HH:mm:ss'}}</div>
        <div>{{this.Message}}</div>
    </div>
</div>

Vorausgesetzt werden Icon, Color, Time und Message. Die Inhaltszeilen bleiben zusammen; der Platz bleibt auch bei fehlendem Symbol ausgerichtet. Ergänze right in der Klassenliste des Containers für die andere Seite. --list-icon-size und --list-icon-gap bestimmen Platzgröße und Abstand. Diese Klassen ordnen verfasstes Markup an; Maps fügen keine automatischen Rahmen ein und positionieren keine Symbole.

Diagnosen

Syntaxhinweise prüfen die Quelltextstruktur. Eine syntaktisch gültige Vorlage kann zur Laufzeit trotzdem durch unbekannte Helfer, ungültige Argumente oder ungeeignete Daten scheitern. Editorvorschauen zeigen Diagnosen und beigetragene Zeilenklassen.

Diagnose	Typische Ursache und Abhilfe
syntax	Nicht geschlossener Block oder fehlerhafter Ausdruck. Quelltext vor dem Speichern korrigieren.
render	Unbekannter Helfer oder anderer Ausführungsfehler. Namen und Argumenttypen prüfen.
missing-reference	renderMap findet Map, deklarierte Ausgabe, Treffer oder gesetzten Wert nicht. Namen, Regeln und lückenhafte Werte prüfen.
type	renderMap zielt auf einen gewöhnlichen Wert statt einer Text-/HTML-Vorlage. map verwenden oder die Definition bewusst ändern.
cycle	Ein aktives Fragment ruft sich direkt oder indirekt selbst auf. Abhängigkeit auflösen.
depth	Mehr als 32 aktive Fragmentaufrufe. Verschachtelung reduzieren.
row	Ungültige Klassendeklaration oder Metadaten im Textmodus. Deklaration korrigieren/absichern.

Ein fehlgeschlagenes Fragment bleibt lokal leer; umgebender Eintragsinhalt bleibt sichtbar. Es wird nicht nochmals mit der Fallback-Regel versucht. Wiederholte aufeinanderfolgende Aufrufe desselben Fragments sind erlaubt; Zyklenschutz betrifft aktive verschachtelte Aufrufe. Scheitert die äußere Elementvorlage selbst, bleiben ihr HTML und ihre Zeilenklassen leer.

Für Regelvergleiche dient Map testen, für Kontext/Darstellung die Fragmentvorschau. Beide Vorschauen beantworten unterschiedliche Fragen.