FreeMarker - Kurzeinführung - Thorsten H. Willert

Übersicht

Mit der Template Engine FreeMarker lassen sich hervorragend Text-Vorlagen aller Art erstellen, sei es für HTML, XML, jede Art von Programmiersprachen (die Quelltexte unterstützen) oder auch für Grafik-Formate wie SVG oder PostScript, obwohl das Ganze auf HTML ausgerichtet ist.

Um FreeMarker lokal auszuführen ist der Einsatz von FMPP (FreeMarker-based File PreProzessor) unverzichtbar.
Dieser erweitert FreeMarker auch noch um einige Features wie z. B. das Laden von Dateien als Datenquelle.

Ich möchte hier keinen Einführungskurs im Programmieren geben, daher richten sich die Beispiele an jeden mit Erfahrung in anderen Programmiersprachen.
FreeMarker geht weit über das hinaus, was z. B. der Preprozessor in C/C++ leistet, es ist vielmehr schon fast eine eigene Programmiersprache, nur das der Output eben, ähnlich wie in PHP, einfach "nur" Text ist.

Die Ausführliche Dokumentationen sind auf freemarker.org und fmpp zu finden.

Ein Commando-File für jEdit (unterstützt FreeMarker von Haus aus) habe ich unter Commando files veröffentlicht.
Dieses baut auf der Kombination FreeMarker + FMPP auf.

JEdit Fmpp

Die einzelnen Parameter sind in der Dokumentation zu FMPP ausführlich dargestellt.

Grundlegende Beispiele

Ich beginne mit ein paar grundlegenden Beispielen.

Die Leerzeichen, Tabulatoren und Zeilenumbrüche im Template haben direkte Auswirkung auf die Ausgabe!
Diese kann z.B mit den Directiven "compress", "nt" und Steueranweisungen weiter beeinflußt werden.

Directiven

Die Schreibweise ähnelt der von HTML-Tags.

Es gibt zwei Arten davon

Start-tag: <#directivename parameters>
End-tag: </#directivename>

oder für benutzerdefinierte

<@mydirective parameters />

Falls die Directiven nicht veschachtelt sind, ist das End-tag unnötig.

Als Alternative gibt es noch die Möglichkeit alle Directiven in [eckigen] Klammern zu schreiben.
Dazu muss in der ersten Zeile des Templates die Directive [#ftl] stehen.

Eingabe von Daten

Die Eingabe erfolgt meist durch das Template bzw. Include-Dateien.

Mit der Hilfe von FMPP ist es auch möglich Daten direkt aus Dateien (CSV, JSON, Text, slicedText, XML usw.) zu laden.

Beispiel

Umwandlung einer CSV-Datei in eine HTML-Tabelle.

Stunde,Montag,Dienstag,Mittwoch,Donnerstag,Freitag
1,Mathe,Deutsch,Englisch,Mathe,Kunst
2,Sport,Französisch,Geschichte,Sport,Geschichte
3,Sport,"Religion ev,kath",Kunst,,Kunst

Konfiguration von FMPP, über die Datei "config.fmpp".
Die CVS-Datei "Beispiel.csv" wird hier in die Sequence "csv" geladen, mit der im Template weitergearbeitet wird:

logFile: FMPP.log.txt
sourceEncoding: UTF-8
data:
{
csv: csv(Beispiel.csv, {separator:",", trimCells:true})
}

<#ftl output_format="HTML">

<table class="table table-striped table-hover">
	<caption>${.current_template_name?keep_before_last(".")}</caption>
	<thead>
		<tr>
			<#list csv.headers as h>
			<th>${h}</th>
			</#list>
		</tr>
	</thead>
	<tbody>
	<#list csv as row>
		<tr>
		<#list row as cell>
			<td>${cell?chop_linebreak?trim}</td>
		</#list>
		</tr>
	</#list>
	</tbody>
</table>

<table class="table table-striped table-hover">
	<caption>CSV2HTML</caption>
	<thead>
		<tr>
			<th>Stunde</th>
			<th>Montag</th>
			<th>Dienstag</th>
			<th>Mittwoch</th>
			<th>Donnerstag</th>
			<th>Freitag</th>
		</tr>
	</thead>
	<tbody>
	<tr>
			<td>1</td>
			<td>Mathe</td>
			<td>Deutsch</td>
			<td>Englisch</td>
			<td>Mathe</td>
			<td>Kunst</td>
	</tr>
	<tr>
			<td>2</td>
			<td>Sport</td>
			<td>Französisch</td>
			<td>Geschichte</td>
			<td>Sport</td>
			<td>Geschichte</td>
	</tr>
	<tr>
			<td>3</td>
			<td>Sport</td>
			<td>Religion ev,kath</td>
			<td>Kunst</td>
			<td></td>
			<td>Kunst</td>
	</tr>
	</tbody>
</table>

CSV2HTML
Stunde	Montag	Dienstag	Mittwoch	Donnerstag	Freitag
1	Mathe	Deutsch	Englisch	Mathe	Kunst
2	Sport	Französisch	Geschichte	Sport	Geschichte
3	Sport	Religion ev,kath	Kunst		Kunst

Ausgabe

Ausgaben von Anweisungen oder Variablen erfolgen immer folgendermaßen:
${Variable_oder_Anweisung}
Jeder sonstige Text im Template wird ausgegeben, wie er dort steht.

Dies komplette Ausgabe muss nicht in einer Datei stattfinden, sondern kann auch in verschiedene Dateien erfolgen.
Am einfachsten geht dies über FMPP-Macro @pp.changeOutputFile.

Kommentare

Kommentare sind ebenfalls fast wie in HTML aufgebaut:
<#-- Das ist ein Kommentar -->

Zuweisungen

Alle Variablen sind Case-Sensitive.
Alle Variablen sind typenlos (Variant).

Einfache Zuweisungen

Beispiele:

<#assign user = "Blubber">${user}
<#assign s = "Hallo ${user}!">${s}
<#assign s = "Hallo " + user + "!">${s}
<#assign zahl = 10>
<#assign zahl2 = 20 zahl3 = 30 >
Produkt: ${zahl1 * zahl2 * zahl3}

Ausgabe:

Blubber
Hallo Blubber!
Hallo Blubber!
Produkt: 6000

Erweiterte Zuweisungen

Beispiele:

<#-- Inkrement -->
<#assign zahl = 10>
<#assign zahl++ >
${zahl}

<#-- Sequencen -->
<#assign seq = ["foo", "bar", "baz"]>
${seq?first}
${seq[2]}<#-- Basis 0 -->

Ausgabe:

11
foo
baz