Die Vorlagensprache

Worum es geht

Der Quelltext einer Vorlage ist FreeMarker. FreeMarker ist eine Vorlagensprache für Java: normaler Text mit Platzhaltern wie ${title} und Anweisungen wie <#if> und <#list>. CRMS führt sie in einer Sandbox aus. Das ist eine abgeschottete Umgebung, in der eine Vorlage nur die Daten sieht, die du ihr gibst, und sonst nichts erreicht.

Was die Vorlage schreibt

Was eine Vorlage ausgibt, hängt von ihrer Ausgabeart ab. Danach richtet sich auch das automatische Escaping.

Escaping heißt: Zeichen wie < und & in einem Wert werden so umgeschrieben, dass sie als Text erscheinen und kein Markup werden. Steht in der Payload <script>alert(1)</script>, schreibt <p>${title}</p> daraus <p>&lt;script&gt;alert(1)&lt;/script&gt;</p>. Die Einzelheiten zu jedem Format stehen unter Ausgabearten und Formate.

Auf die Payload zugreifen

Die Payload ist die oberste Ebene der Vorlage. Ihre Felder sind direkt da.

<#-- Payload: { "title": "Audit Halle 3", "customer": { "name": "ACME" },
                "items": [ { "label": "HACCP", "amount": 480 } ] } -->
<h1>${title}</h1>
<p>Kunde: ${customer.name}</p>
<table>
  <#list items as item>
    <tr><td>${item.label}</td><td>${item.amount}</td></tr>
  </#list>
</table>
<p>Prüfer: ${(inspector)!"–"}</p>
<#if remarks?has_content><p>${remarks}</p></#if>

• ${…} gibt einen Wert aus, escaped.
• <#list> läuft über eine Liste, <#if> prüft eine Bedingung.
• ! setzt einen Ersatzwert, wenn ein Feld fehlt. ?? fragt, ob es da ist.
• <#assign>, <#macro> und <#function> bauen Hilfen innerhalb desselben Quelltexts. Die Hub-Vorlagen machen davon reichlich Gebrauch, etwa für Überschriften und das Inhaltsverzeichnis.

Die Payload hat höchstens zwei Ebenen: title, customer.name, items[].amount. Tiefer geht es nicht. Was CRMS an der Payload prüft, steht unter Die Payload-Prüfung.

Zahlen, Daten, Wahrheitswerte

CRMS setzt für jede Ausgabe die Sprache und die Zeitzone des Dokuments. Danach formatiert FreeMarker:

Ein Feld, das die Revision als DATE oder DATETIME deklariert, wird zu einem echten Datum, auch wenn es als ISO-Text kommt. So kommt es aus JSON. Ein DATE ist Mitternacht in der Zeitzone des Dokuments, nie in der des Servers. Ohne Deklaration bleibt ein ISO-Text ein Text. Woher Sprache und Zeitzone kommen, steht unter Sprache und Zeitzone.

Assets

Ein Asset der Revision nennst du mit asset:<name>. Was CRMS daraus macht, hängt vom Format ab:

<img src="asset:logo.png" alt="Logo"/>

Nennt die Vorlage ein Asset, das die Revision nicht hat, schlägt das Rendern fehl, bei HTML mit render-asset-unknown.

Bilder, die zur Anfrage gehören, etwa eine Unterschrift oder Fotos einer Begehung, sind keine Assets. Die Vorlage nennt sie attachment:<name>. Mehr unter Bilder und SVG.

SVG aus der Payload: crms.svg

Eine Grafik, die der Aufrufer selbst zeichnet, zum Beispiel ein Diagramm, kommt als SVG-Text in der Payload. Ausgeben würde sie das Escaping nur als Text. Dafür gibt es die Funktion crms.svg:

<div class="figure">${crms.svg(diagramSvg)}</div>

CRMS prüft das SVG gegen eine Liste erlaubter Elemente und Attribute und setzt es dann ein. crms gehört CRMS: Ein Payload-Feld namens crms ersetzt die Funktion nicht.

Was erlaubt ist und was abgewiesen wird, steht unter Bilder und SVG.

Was gesperrt ist

Dazu kommen Grenzen beim Rendern: Die Ausgabe hat eine Höchstgröße, und eine Vorlage, die nicht endet, wird nach der Zeitgrenze abgebrochen. Siehe Ausführung und Grenzen.

Fehler in der Vorlage

Fehler kommen als Schlüssel mit Zeile und Spalte im Quelltext. Den Text von FreeMarker bekommt der Client nicht.

Einen Syntaxfehler findet CRMS schon beim Einreichen. Der Renderer parst den Entwurf, und eine Revision, die sich nicht parsen lässt, entsteht gar nicht: 422 template-source-rejected mit violations: [{"field": "source", "rule": "template-syntax-error|1|7"}].

Fallen

Weiter

• Wie eine Vorlage aufgebaut ist
• Die Payload-Prüfung
• Bilder und SVG