Vorlagen-Syntax

Eine Moliri-Vorlage ist eine gewöhnliche Word-Datei (.docx), in deren Text Befehle der Form {# … #} stehen.

Moliri liest den literalen Text des Dokuments (Fließtext, Tabellenzellen, Kopf- und Fußzeilen) und führt jeden Befehl als JavaScript-Ausdruck aus. Ob der Befehl in einem Steuerelement steht, wie es der Vorlagen-Editor anlegt, oder als einfacher Text, spielt dafür keine Rolle.

Die Befehle

Innerhalb eines Befehls gilt JavaScript-Syntax. Zeichenketten in Backticks und Template-Literale (`${…}`) funktionieren.

{#$o[`RegNr`] ?? ``#}
{#! FLOAT_FORMAT = { "mask": "Number", "scale": "2", "thousandsSeparator": " ", "radix": "," }#}
{# IMAGE img(eingang[$i], { width: 16 }) #}
{# LINK ({ url: `https://beispiel.moliri.app/p/${p.projektID}/o/${$o.objektID}`, label: `Objekt öffnen` }) #}

Die Regel für Schleifenvariablen

Die häufigste Fehlerquelle. Innerhalb einer FOR-Schleife heißt die Laufvariable mit $ davor:

{# FOR file IN $f #}
  {# IMAGE img($file, { width: 6 }) #}     ← richtig: $file
  {# IMAGE img(file, { width: 6 }) #}      ← falsch: file ist undefiniert
{# END-FOR file #}

Das gilt für jede Schleife: FOR obj IN objects ergibt $obj, FOR i IN _.range(0, n) ergibt $i. Zusätzlich steht in jeder Schleife $idx bereit, der Index der innersten Schleife, beginnend bei 0. Eine laufende Nummer ist damit {#$idx + 1#}.

In einer Tabelle stehen FOR und END-FOR in eigenen Zeilen, FOR über der Datenzeile und END-FOR darunter. Dann wiederholt sich die Datenzeile für jedes Element. So entstehen Objektlisten als Tabelle, siehe Rezepte . Stehen beide in der ersten und letzten Zelle derselben Zeile, wiederholt die eingebaute Engine nur die Zellen, nicht die Zeile.

Backticks statt Anführungszeichen

Word ersetzt gerade Anführungszeichen gern durch typografische. Moliri gleicht das beim Export aus, und auch die Felderkennung versteht typografische Anführungszeichen. Backticks sind trotzdem die bessere Wahl. Die verändert Word nie, und sie erlauben zugleich Template-Literale.

Einfache Ausgabe

{#$o[`RegNr`] ?? ``#}

$o ist das aktuelle Objekt, der Feldname steht in eckigen Klammern. Der leere Rückfall nach ?? sorgt dafür, dass ein Feld ohne Wert leer bleibt und keine Folgefehler auslöst.

Bedingung

{# IF $o[`Inventarstatus`] === `Dauerleihgabe` #}
Dauerleihgabe
{# END-IF #}

Schleife über Objekte

{# FOR obj IN objects #}
{# $obj[`RegNr`] ?? `` #}
{# $obj[`Originaltitel`] ?? `` #}

{# END-FOR obj #}

Felderkennung und Nachladen

Moliri lädt für den Export nur die Felder, die die Vorlage verwendet. Erkannt wird jeder Feldname, der in eckigen Klammern und Anführungszeichen steht: $o[`Feld`], $obj[`Feld`] in Schleifen und auch o[`Feld`] in einer Gruppierungsfunktion. Bei Schlüsseln ohne $o oder Laufvariable davor zählen nur Namen, die einem Feld des Projekts entsprechen.

Nicht erkannt wird ein Feldname, der anders in den Befehl kommt, etwa als berechneter Schlüssel oder als Zeichenkette in _.groupBy(objects, `Leihgeber`). Ein solches Feld lässt sich in einer nie ausgeführten Bedingung sichtbar machen:

{# IF false #}
{# INS $o[`Leihgeber`] ?? `` #}
{# END-IF #}

Dateien lädt Moliri nur, wenn die Vorlage $f oder files erwähnt. Reine Datenvorlagen bleiben dadurch schnell.

Ein Dokument oder eines je Objekt

Moliri erkennt den Modus an den Befehlen:

• Schleife über die Objekte, ein Dokument. Sobald eine FOR-Schleife über die Objektmenge läuft, wird die Vorlage genau einmal mit allen Objekten gerendert. Erkannt wird jede FOR, deren Quelle objects oder eine daraus zugewiesene Variable nennt: FOR obj IN objects, FOR obj IN objects.filter(…) und auch {#! gruppen = _.groupBy(objects, …) #} mit FOR key IN Object.keys(gruppen). Datei- und Indexschleifen (FOR file IN $f, FOR i IN _.range(…)) zählen nicht.
• Sonst ein Dokument je Objekt, anschließend zusammengeführt oder als ZIP gepackt.

objects ohne Schleife ändert den Modus nicht. {#objects.length#} in einer Vorlage je Objekt gibt die Gesamtzahl aus und bleibt eine Vorlage je Objekt.

Abschnittsverhalten beim Zusammenführen

Bei einem Dokument je Objekt bestimmt das Abschnittsverhalten, wie die Einzeldokumente verbunden werden:

Die Werte sind stabil und werden nicht umbenannt. Der Name der Ausgabedatei ist <Vorlagenname>_<JJJJ-MM-TT>.docx bzw. .zip.

Einstellungen reisen im Dokument

Der Vorlagen-Editor speichert im rechten Panel (Reiter Ausgabe) drei Einstellungen als unsichtbaren Marker in der Vorlage: Steuerelemente auflösen, Objekt-Modus und Abschnittsverhalten. Beim Export liest Moliri den Marker. Die Vorlage bringt ihre Voreinstellungen also mit, egal wer sie verwendet.

Fehlt der Marker, etwa bei einer in Word geschriebenen Vorlage, gilt: Steuerelemente werden zu Klartext aufgelöst, der Modus wird erkannt, das Abschnittsverhalten ist template. Im Exportdialog lassen sich Zusammenführung und Steuerelemente unter Erweiterte Einstellungen für einen Lauf übersteuern.

Grenzen

Die Prüfung im Vorlagen-Editor findet dieselben Fehler vor dem Export. Nicht geschlossene FOR- und IF-Blöcke und unlesbare Vorlagen meldet sie immer, JavaScript-Fehler prüft sie mit echten Beispieldaten.

Weiterlesen

• Vorlagen-Variablen : welche Daten verfügbar sind
• Vorlagen-Funktionen : die zehn Hilfen
• Rezepte : kopierbare Muster
• Word-Berichte : der Export