Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

In Notification Templates können verschiedene Placeholder definiert werden. Diese werden dann ersetzt durch entsprechende Texte oder Links.

TODO Document all placeholders

...

Placeholder

...

Beschreibung

...

{{ObjectUrl}}

...

URL in E-Mail

Damit der Link korrekt gebildet wird muss die Konfiguration der Base URL erfolgen mit Server:BaseURL (TODO Korrektes Setting). Siehe Grundeinstellungen

...

{{ObjectMarkdownLink}}

Link in Markdown

...

Templates für Benachrichtigungen und Reports können mit dynamischen Inhalten und Strukturen gestaltet werden. Dazu kann Liquid als Template-Sprache in Bloqs verwendet werden.

Die Dokumentation von Liquid bietet detaillierte Informationen über die Verwendung der Template-Sprache. Von der Syntax, der Handhabung von Listen und Konditionen bis zur Verwendung von Filter ist dort alles beschrieben. Darum beschränken sich die weiteren Abschnitte ausschliesslich auf die für Bloqs spezifischen Eigenschaften und Anwendungsfälle.

Table of Contents
stylenone

🚀 Getting Started

Um Templates zu Erstellen und zu Testen, steht das Admin-Tool Template-Tester zur Verfügung. Mit diesem Tool können Templates mit echten Daten angereichert und eine Vorschau generiert werden.

image-20241223-094415.pngImage Added

Im Tester kann ein Kontext-Objekt als Basis für das Template ausgewählt werden. Das Template wird dann mit den Daten von diesem Objekt angereichert.

...

📝 Kontext, Objekt und Eigenschaften

Im Template steht normalerweise ein Objekt als Kontext zur Verfügung. D.h. es kann direkt auf die Eigenschaften des Objekts zugegriffen werden.

Beispielsweise können bei einer Person direkt die Eigenschaften {{ FirstName}} und {{ LastName }} im Template verwendet werden.

Zusätzlich stehen folgende Eigenschaften, unabhängig von der Metaklasse des Objekts zur Verfügung:

Eigenschaft

Beschreibung

Beispiel

ObjectTitle

Der Titel des Hauptobjektes

Subject für eine E-Mail mit dem Namen des veränderten Objektes:
Objekt {{ObjectTitle}} wurde verändert

ObjectId

Der Primärschlüssel des Hauptobjektes

ObjectMetaClass

Der Name der Meta-Klasse des Hauptobjektes

ObjectUrl

Absolute URL (z.B. für E-Mail)

Für korrekte Funktion muss Server:ApplicationDomainBasePath gesetzt sein (siehe Konfigurationsschlüssel)

E-Mail Text mit Link auf das veränderte Objekt:
...
Das veränderte Objekt: {{ObjektUrl}}
...

ObjectMarkdownLink

Link in Markdown

Für korrekte Funktion muss Server:ApplicationDomainBasePath gesetzt sein (siehe Konfigurationsschlüssel)

Der Link auf das betroffene Objekt in einer In-App Notification mit dem der User direkt auf das Objekt navigieren kann:
Das Requirement {{ObjektMarkdownLink}} wurde verändert.

📧 Eigenschaften von Benachrichtigungen

Bei Benachrichtigungen stehen zusätzlich folgende Eigenschaften zur Verfügung:

Eigenschaft

Beschreibung

Beispiel

Assignee oder Addressee

Empfänger der Notification

Originator

Benutzer der die Benachrichtigung initiiert hat.

Notification

Liefert das Objekt auf die Instanz der Benachrichtigung selbst. So kann auf die Properties der Notification zugegriffen werden.

Datum an dem die Benachrichtigung initiiert wurde.

{{Notification.IssueDate}}

Ereignisparameter

Zusätzlich zu der Liste der oben definierten Eigenschaften stehen bei Benachrichtigungen die Ereignisparameter zur Verfügung:

...

⚡ Expressions

Mit dem Expression-Tag {% exp ... %} können Expressions im Template integriert werden. Viele der Funktionen, die als Expression zur Verfügung stehen, können aber direkt in Liquid implementiert werden. Die Liquid-Implementation ist dann zu bevorzugen.

Beispiele:

  • {% exp 2 == 2 %} wird zu True

  • {% exp String.toupper(Value) %} wird zu ENCODO bei Value = Encodo

🖼️ Bilder

Um Bilder in HTML-Templates darzustellen, steht der Filter image zur Verfügung.

Einfaches Bild

{{ Stream | image type: 'image/svg+xml' }}

Bild mit “alt” Text

{{ Stream | image type: 'image/svg+xml' alt: 'Logo' }}

Bild mit “alt” Text und Grösse

{{ Stream | image type: 'image/svg+xml' alt: 'Logo' width: '200' height: '100' }}

Damit das Bild korrekt dargestellt werden kann, muss zwingend der Media-Type angegeben werden.

Übersicht über verschiedene Media-Types: https://wiki.selfhtml.org/wiki/MIME-Type/%C3%9Cbersicht#I

Markdown to Html

Um Markdown-Inhalte eines Felds zu Html zu konvertieren, steht der Filter markdown_to_html zur Verfügung.

Beispiel:

  • {{ MyMarkdownField | markdown_to_html }}

➡️ Migration von Templates

Liquid kennt keine Strukturen [[ ... ]] wie bei bestehenden Templates. Dafür können mithilfe von Control flow und Iterationen viel komplexere und feinere Templates umgesetzt werden.

Beispiel für eine Migration eines bestehenden Templates mit Strukturen.

  • Der Prefix Object. für das Basisobjekt sollte nicht mehr verwendet werden.

  • Die Struktur [[List:]] wird durch Control Flow und Iterationen in Liquid ersetzt.

  • Die Liquid-Syntax bevorzugt Leerzeichen innerhalb von {{ ... }} und {% ... %}

Bestehendes Template

Liquid Template

Code Block
Hi {{Object.FirstName}} {{Object.LastName}}
 
This is an e-mail template with some lead-in text and then some blocks.
 
[[List: Source="Company.Offices"]]
[[Header]]
ListHeader:
[[/Header]]
[[Detail VisibleIf="1==1"]]
{{Item.Name}}
[[/Detail]]
[[Detail VisibleIf="1==2"]]
Not visible
[[/Detail]]
[[Footer]]
ListFooter
[[/Footer]]
[[/List]]
 
Thanks & Greets
 
{{Company.Name}}
Code Block
Hi {{ FirstName }} {{ LastName }}
 
This is an e-mail template with some lead-in text and then some blocks.

{% if Company.Offices.size > 0 %}
ListHeader:
{% for office in Company.Offices %}
{% if 1 == 1 %}
{{ office.Name }}
{% endif %}
{% if 1 == 2 %}
Not visible
{% endif %}
{% endfor %}
ListFooter
{% endif %}

Thanks & Greets
 
{{ Company.Name }}