Erstellen von Freemarker-basierten Word-Vorlagen#

Eine Freemarker-basierte Word-Vorlage ist ein gewöhnliches Word-Dokument (.docx), das Freemarker-Ausdrücke enthält. Sie gestalten das Dokument in MS Word mit eigenen Formatvorlagen, Kopf- und Fußzeilen sowie Tabellen und schreiben die Ausdrücke überall dort hinein, wo Vorgangsdaten erscheinen sollen. Beim Export setzt Allegra die Werte der Ausdrücke ein und liefert ein Word-Dokument zurück.

Anders als bei Legacy-Vorlagen (siehe Erstellen von Legacy-Word-Vorlagen) benötigen Sie weder ein Word-Plug-In noch Inhaltssteuerelemente. Die Vorlage bestimmt das gesamte Layout des Dokuments.

Word-Dokument in eine Freemarker-Vorlage umwandeln#

Allegra verwendet die Freemarker-Engine nur für Word-Vorlagen, die dies ausdrücklich anfordern. Dazu legen Sie benutzerdefinierte Dokumenteigenschaften an:

Öffnen Sie in MS Word das Dokument, das Sie als Vorlage verwenden möchten.
Gehen Sie zu Datei > Informationen > Eigenschaften > Erweiterte Eigenschaften und öffnen Sie die Registerkarte Anpassen.
Fügen Sie eine Eigenschaft namens allegraTemplateEngine vom Typ Text mit dem Wert freemarker hinzu.
Fügen Sie bei Bedarf weitere Einstellungen aus der folgenden Liste hinzu.
Speichern Sie das Dokument und laden Sie es unter Verwaltung > Vorlagen > Exportvorlagen hoch.

Eine Word-Vorlage ohne allegraTemplateEngine=freemarker wird als Legacy-Vorlage behandelt.

Bemerkung

Allegra entfernt seine eigenen allegra…-Eigenschaften aus dem exportierten Dokument. Benutzerdefinierte Eigenschaften, die Sie selbst angelegt haben, bleiben erhalten.

Vorlageneinstellungen#

Diese Einstellungen entsprechen den Einstellungen für HTML-Vorlagen (siehe Erstellen von HTML-Vorlagen), ergänzt um das Präfix allegra. Für Ja/Nein-Einstellungen können Sie den Word-Eigenschaftstyp Ja oder nein verwenden oder true, yes bzw. 1 als Text eingeben.

Eigenschaft	Standard	Beschreibung
`allegraTemplateEngine`		Muss `freemarker` sein.
`allegraTemplateTarget`	(keiner)	`1` - Export von Wiki-Dokumenten, `2` - Export von Vorgängen. Ist diese Eigenschaft nicht gesetzt, wird die Vorlage für alle Exportarten angeboten.
`allegraIncludeHistory`	ja	Lädt die Vorgangshistorie, die Kommentare und die internen Kommentare.
`allegraIncludeCosts`	ja	Lädt die gebuchten Kosten.
`allegraIncludeBudgetPlan`	ja	Lädt die Budget- und Planwerteinträge.
`allegraIncludeLinks`	nein	Lädt die verknüpften Vorgänge. `item.links` bleibt leer, solange diese Eigenschaft nicht gesetzt ist.
`allegraIncludeChildren`	nein	Fügt die untergeordneten Vorgänge der exportierten Vorgänge zu `item.children` hinzu.
`allegraOpenChildrenOnly`	nein	Zusammen mit `allegraIncludeChildren` werden nur untergeordnete Vorgänge hinzugefügt, die nicht geschlossen sind.
`allegraFullHierarchy`	nein	Zusammen mit `allegraIncludeChildren` werden alle Nachfahren hinzugefügt, nicht nur die direkt untergeordneten Vorgänge.

Das Laden von Historie, Kosten und Budget verlangsamt den Export. Wenn Ihre Vorlage diese Daten nicht verwendet, setzen Sie die entsprechenden Eigenschaften auf no.

Ausdrücke in Word schreiben#

Word-Vorlagen verwenden für Direktiven die Syntax mit eckigen Klammern von Freemarker, weil Word die spitzen Klammern, die Sie eingeben, maskiert:

[#list items as item]
  ${item.no} ${item.synopsis}
[/#list]

[#if item.fields["Status"] == "closed"]closed[/#if]

[#-- a comment --]

Interpolationen schreiben Sie weiterhin als ${...}. Sie können Ausdrücke direkt in den Dokumenttext eingeben und beliebig mit Word formatieren. Allegra korrigiert die typografischen Anführungszeichen und Gedankenstriche, die die AutoKorrektur von Word in Ausdrücke einfügt. Sie müssen die AutoKorrektur also nicht ausschalten.

Absätze und Tabellenzeilen#

Enthält ein Absatz nur Direktiven wie [#list ...] oder [/#if], entfernt Allegra den ganzen Absatz. Eine Direktive in einer eigenen Zeile hinterlässt deshalb keine Leerzeile in der Ausgabe.
Ein Absatz mit mindestens einer ${...}-Interpolation bleibt erhalten. So wird [#if item.project??]Project: ${item.project}[/#if] in einer eigenen Zeile zu einer Zeile, die nur erscheint, wenn die Bedingung erfüllt ist.
Um eine Tabellenzeile zu wiederholen, setzen Sie das öffnende [#list ...] in eine eigene Zeile darüber und das schließende [/#list] in eine eigene Zeile darunter. Allegra entfernt diese reinen Direktivenzeilen, und die Zeile dazwischen wird für jeden Eintrag einmal wiederholt.

| Type                          | Item            | Title           |
| [#list item.links as link]    |                 |                 |
| ${link.type}                  | ${link.itemNo}  | ${link.title}   |
| [/#list]                      |                 |                 |

Wichtig

Jede Direktive muss innerhalb derselben Struktur geöffnet und geschlossen werden. Eine Schleife, die in einer Tabellenzelle beginnt und außerhalb der Tabelle endet, erzeugt ein ungültiges Dokument, und der Export schlägt mit der Meldung „The rendered template is not valid WordprocessingML“ fehl.

Kopf- und Fußzeilen#

Ausdrücke funktionieren auch in Kopf- und Fußzeilen, zum Beispiel Exported by ${exportedBy} on ${exportedOnText}. Für Seitenzahlen verwenden Sie die Seitenzahlfelder von Word.

Rich Text#

Vorgangsbeschreibungen, Kommentare und Unterschiede in der Historie liegen als HTML vor. Geben Sie sie mit der Funktion html() aus. Sie wandelt das HTML in Word-Inhalt um und bettet enthaltene Bilder ein:

${html(item.description)}

Mit ${item.description} erscheint das HTML-Markup der Beschreibung als Text.

Der umgewandelte Text verwendet die Standardschriftart der Vorlage (die Schriftart der Formatvorlage Standard), sofern der Rich Text keine eigene Schriftart festlegt.

Sie können html() auch eigenes HTML übergeben. So erstellen Sie einen anklickbaren Link zu einem Vorgang:

${html('<a href="' + item.url + '">' + item.no + '</a>')}

${item.url} allein liefert nur die Adresse als einfachen Text. item.url ist leer, wenn die Server-URL in Allegra nicht konfiguriert ist.

Um den Avatar einer Person anzuzeigen, betten Sie ihn als Bild ein und geben Sie immer eine Größe an. Ohne Größenangabe wird der Avatar in voller Größe angezeigt:

[#if comment.avatar??]${html('<img src="' + comment.avatar + '" style="width:18pt;height:18pt"/>')}[/#if]

Freemarker-Variablen#

Die Vorlage erhält die folgenden Variablen auf oberster Ebene:

Variable	Beschreibung
`items`	Die exportierten Vorgänge (eine Liste von Vorgängen, siehe unten). Beim Export eines Wiki-Dokuments sind dies die Vorgänge, aus denen das Dokument besteht.
`document`	Das exportierte Wiki-Dokument als Vorgang oder null bei einem Vorgangsexport. Prüfen Sie es mit `[#if document??]`.
`html(text)`	Wandelt Rich Text (HTML) in Word-Inhalt um. Siehe Rich Text.
`text(key)`	Gibt den lokalisierten Text eines Allegra-Ressourcenschlüssels in der Sprache des exportierenden Benutzers zurück. Wird der Schlüssel nicht gefunden, wird der Schlüssel selbst angezeigt.
`exportedBy`	Der Name der Person, die den Export ausführt.
`exportedOn`	Der Exportzeitpunkt als Datumswert, den Sie mit Freemarker formatieren können, z.B. `${exportedOn?string["yyyy-MM-dd"]}`.
`exportedOnText`	Der Exportzeitpunkt, bereits für das Gebietsschema des Benutzers formatiert.
`locale`	Der Sprachcode des Benutzers, z.B. `en` oder `de`.
`serverUrl`	Die konfigurierte Server-URL von Allegra.
`licenseHolder`	Der Lizenzinhaber.

Datumswerte im Modell (created, lastModified, createdOn usw.) sind bereits für das Gebietsschema des exportierenden Benutzers formatiert. Sie können sie unverändert ausgeben.

Vorgang#

Attribut	Beschreibung
`id`	Die interne Vorgangs-ID.
`no`	Die Vorgangsnummer, wie sie in Allegra angezeigt wird.
`url`	Der absolute Link zum Vorgang oder leer, wenn keine Server-URL konfiguriert ist.
`synopsis`	Der Titel.
`description`	Die Beschreibung als HTML, in der Allegra-Makros bereits aufgelöst sind. Verwenden Sie `${html(item.description)}`.
`project`	Der Projektname.
`projectTypeId`	Die ID des Projekttyps.
`created`, `lastModified`	Zeitpunkt der Erstellung und der letzten Änderung.
`currencyName`, `currencySymbol`	Die Währung des Projekts, z.B. „Euro“ und „EUR“. Leer, wenn für das Projekt keine Währung festgelegt ist.
`wiki`	`true` für ein Wiki-Dokument, `false` für einen regulären Vorgang.
`fields`	Alle Feldwerte nach Feldname, z.B. `${item.fields["Status"]}`. Die Feldnamen finden Sie unter `Verwaltung` > `Anpassen` > `Vorgangsattribute`.
`fieldsById`	Alle Feldwerte nach `f` + Feld-ID, z.B. `${item.fieldsById["f17"]}`.
`links`	Verknüpfte Vorgänge (siehe unten). Erfordert `allegraIncludeLinks`.
`children`	Untergeordnete Vorgänge mit derselben Struktur. Erfordert `allegraIncludeChildren`.
`history`	Feldänderungen, die neuesten zuerst. Erfordert `allegraIncludeHistory`.
`comments`, `internalComments`	Kommentare und interne Kommentare. Erfordern `allegraIncludeHistory`.
`costs`	Gebuchte Kosten. Erfordert `allegraIncludeCosts`.
`budget`	Budget- und Planwerteinträge. Erfordert `allegraIncludeBudgetPlan`.

Verknüpfung#

Attribut	Beschreibung
`type`	Der Name des Verknüpfungstyps.
`itemId`, `itemNo`, `title`, `status`	ID, Nummer, Titel und Status des verknüpften Vorgangs.
`url`	Der absolute Link zum verknüpften Vorgang oder leer.
`included`	`true`, wenn der verknüpfte Vorgang ebenfalls Teil dieses Exports ist.

Kommentar#

Attribut	Beschreibung
`author`, `authorId`	Name und ID des Autors.
`createdOn`	Zeitpunkt, zu dem der Kommentar geschrieben wurde.
`text`	Der Kommentar als HTML. Verwenden Sie `${html(comment.text)}`.
`avatar`	Der Avatar des Autors als eingebettetes Bild (Data-URI) oder null.

Historieneintrag#

Attribut	Beschreibung
`changedBy`, `changedById`	Name und ID der Person, die die Änderung vorgenommen hat.
`changedOn`	Zeitpunkt der Änderung.
`field`	Der Name des geänderten Felds.
`diff`	Alter und neuer Wert als HTML, wie auf der Registerkarte „Historie“. Verwenden Sie `${html(entry.diff)}`.
`avatar`	Der Avatar der Person, die die Änderung vorgenommen hat, oder null.

Kosten#

effortDate, person, subject, description, hours, cost, currency.

Budgeteintrag#

changedOn, changedBy, description, estimatedHours, estimatedCost, currency sowie plannedValue (true für einen Planwerteintrag, false für einen Budgeteintrag).

Bemerkung

Freemarker bricht mit einem Fehler ab, wenn ein Ausdruck null ist. Für Werte, die fehlen können, wie document oder avatar, verwenden Sie [#if x??] oder einen Standardwert wie ${x!""}.

Beispiele#

Vorgänge mit ihren Feldern und ihrer Beschreibung:

[#list items as item]
${item.no} ${item.synopsis}
Project: ${item.project}    Status: ${item.fields["Status"]!""}
${html(item.description)}
[/#list]

Vorgangshierarchie mit einem rekursiven Makro (erfordert allegraIncludeChildren):

[#macro render item]
${item.no} ${item.synopsis}
${html(item.description)}
[#list item.children as child][@render child/][/#list]
[/#macro]
[#list items as item][@render item/][/#list]

Kommentare:

[#if item.comments?has_content]
Comments
[#list item.comments as comment]
${comment.author}, ${comment.createdOn}
${html(comment.text)}
[/#list]
[/#if]

Titel des Wiki-Dokuments, ersatzweise der Titel des ersten Vorgangs:

[#if document??]${document.synopsis}[#else]${items[0].synopsis}[/#if]

Fehlerbehebung#

Kann eine Vorlage nicht verarbeitet werden, zeigt der Export die Fehlermeldung von Freemarker an, einschließlich des Ausdrucks, der den Fehler verursacht hat. Bei anderen Fehlern enthält die Meldung einen kurzen Referenzcode. Geben Sie diesen Code an Ihren Administrator weiter, der damit die Ursache im Serverprotokoll finden kann.

Ein Ausdruck erscheint wörtlich in der Ausgabe: Prüfen Sie die Schreibweise und ob die Direktive eckige Klammern verwendet ([#if], nicht <#if>).
Der Export schlägt mit „not valid WordprocessingML“ fehl: Eine Direktive wird in unterschiedlichen Absätzen oder Tabellen geöffnet und geschlossen. Siehe Absätze und Tabellenzeilen.
Eine Liste ist leer: Prüfen Sie, ob die entsprechende allegraInclude…-Eigenschaft gesetzt ist.