Templates

Doel

Flowmailer ondersteunt het gebruik van templates, waarmee gebruikers mooie en professioneel opgemaakte e-mails kunnen versturen zonder ze in elk bronsysteem te hoeven bouwen. Gebruikers hebben volledige controle over templates door de HTML te bewerken, maar Flowmailer biedt ook een makkelijk te gebruiken, meer visuele "WYSIWYG" Quick editor. Daarnaast bieden we ook een volledig pakket van design, HTML omzetting en overige template diensten om u compleet werkende oplossingen te kunnen bieden.

Onze templates zijn gebaseerd op de Freemarker template engine. Dit maakt alle denkbare templates mogelijk, van eenvoudig tot zeer complex. Personalisatie, conditionele content, lijsten van meerdere niveaus diep en nog veel meer. Flowmailer voegt daar vervolgens eigen functies aan toe, speciaal voor gebruik in e-mail. Denk hierbij bijvoorbeeld aan code die een link naar de online versie toevoegt. Ben je een ontwikkelaar? Maak simpelweg gebruik van de objecten die je al hebt (bv. een bestelling), zet ze om naar JSON en geef die aan Flowmailer. Wij zorgen er voor dat daar een mooie mail uit komt (bv. bestellingsbevestiging).

Flowmailer beschikt ook over unieke mogelijkheden om gebruik te maken van de content die het bronsysteem verstuurt. Hierdoor kunnen gebruikers mooie, responsive e-mails versturen zonder iets te hoeven veranderen aan het bronsysteem. We kunnen bijvoorbeeld simpelweg een header en footer toevoegen, maar ook specifieke delen (of zelfs losse velden) uit het originele bericht op een hele andere manier hergebruiken.

Quick editor

Los van de complexe logica die onze templates kunnen bevatten, bestaan veel templates voornamelijk uit tekst en afbeeldingen met enkele variabele velden. Die (delen van) templates kunnen eenvoudig bewerkt worden zonder enige technische kennis, met behulp van onze Quick editor.

Template engine

Freemarker

In plaats van het wiel opnieuw uitvinden heeft Flowmailer ervoor gekozen om de bekende en vrij verkrijgbare Freemarker engine als basis te nemen voor onze templates. Dit betekent dat de meeste syntax en ingebouwde functionaliteit ondersteund door Flowmailer ook in de Freemarker documentatie te vinden is. Flowmailer voegt specifieke functionaliteit toe om onze specifieke usecases te ondersteunen. Voorbeelden hiervan zijn 'online versie' links en delen van templates als bewerkbaar markeren met behulp van onze Quick Editor.

Toepasbaarheid

Flowmailer ondersteunt op allerlei plekken templates. De meest voor de hand liggende daarvan is HTML bericht templates. Daarnaast gebruiken we templates voor zaken die we flexibel willen maken. Zo is het mogelijk om alle template functies die we op deze pagina omschrijven te gebruiken in een Subject FlowStep om dynamisch het onderwerp van een bericht te herschrijven. Andere voorbeelden hiervan zijn text templates (ook voor SMS) en URL instellingen van de External Content en External Data FlowSteps.

Let op: Templates bieden veel flexibiliteit, maar het is ook makkelijk om iets stuk te maken. Wees vooral voorzichtig met het bewerken van templates die actief worden gebruikt. Flowmailer controleert de geldigheid van templates als je ze opslaat, maar niet alles kan op dat moment worden gecontroleerd. Als er iets stuk is en een foutmelding veroorzaakt, zal Flowmailer het getroffen bericht in de "Held messages" lijst stoppen en een notificatie hiervan geven. Je kunt de foutmelding dan lezen, het probleem oplossen en gebruik maken van de Retry functie.

Basis gebruik

Variabelen

Je kunt gebruik maken van variabelen om informatie op te slaan zoals tekst en getallen, maar ook om te verwijzen naar gestructureerde data zoals een lijst. Variabelen kunnen worden gebruikt om bijvoorbeeld een tekst op een bepaalde plaats weer te geven. Alle gegevens die beschikbaar zijn in de context van een Flow zijn beschikbaar als variabelen voor gebruik in templates. Als de bron bijvoorbeeld een variabele genaamd 'firstName' mee stuurt, kun je deze als volgt weergeven in een template:

${firstName}

In sommige gevallen wil je misschien zelfs gebruik maken van variabelen die in een gelaagde structuur genaamd een 'hash' zijn geplaatst. Bijvoorbeeld als er een bestelling wordt meegestuurd waarvan het ID getoond moet worden:

${bestelling.id}
Alternatieve/standaard waarden

Vaak is de volgende vraag: "Wat als de variabele ontbreekt?". Goede vraag! We willen graag dat je een bewuste beslissing neemt over wat er in zo'n geval moet gebeuren. Standaard zijn daarom alle variabelen verplicht, wat zal leiden tot een foutmelding als er één ontbreekt. Je kunt dat gedrag aanpassen door een "!" toe te voegen. Daarna kan er ook nog een alternatieve waarde worden gekozen:

Beste ${voornaam!"klant"},

Als de voornaam variabele ontbreekt zal de alternatieve waarde worden getoond:

Beste klant,
If

If condities kunnen worden gebruikt om delen van een template alleen onder bepaalde voorwaarden te gebruiken. Content en template logica (bijvoorbeeld nog een if) kunnen gemengd worden gebruikt binnen het conditionele blok. Bijvoorbeeld, bezorginformatie moet alleen worden getoond bij order waar dit bij van toepassing is:

<#if verzending == "pakket">
  We zullen uw bestelling zo snel mogelijk verzenden!
</#if>

If blokken kunnen ook meerdere voorwaarden bevatten en "elseif" en "else" blokken hebben. Raadpleeg de Freemarker documentatie voor meer voorbeelden.

List

Als je een lijst van dingen hebt, bijvoorbeeld een bestelling die bestelregels bevat, kun je die doorlopen met 'list'. Dit wordt vaak gebruikt in combinatie met HTML lijsten of tabellen, waarbij elk element op een nieuwe rij wordt geplaatst:

<table>
  <#list bestelling.regels as regel>
    <tr>
      <td>${regel.omschrijving}</td>
      <td>${regel.aantal}</td>
    </tr>
  </#list>
</table>

Speciale functies

Online versie

Het maken van een 'online versie' link vereist speciale code, omdat deze voor elk bericht anders is en nog niet bekend is als je het template toepast. We hebben dat opgelost door daar een speciale macro voor beschikbaar te maken:

<a href="<@onlineLinkUrl/>">Lees online</a>

Let op! Voor het maken van een online versie link is tevens archiveren middels een Archive FlowStep vereist, want dat is waar we hier naar linken. Als het archiveren ontbreekt maar het template vereist dit zal Flowmailer het bericht niet afleveren. De Archive Flowmailer hoeft niet voor het template met de online link te staan, deze mag bijvoorbeeld gewoon aan het einde van de Flow.

Bewerkbare delen

Om delen van een template als bewerkbaar te markeren in de Quick editor (alleen echte bericht templates, niet van toepassing op FlowStep settings) kan de volgende code worden gebruikt:

<table>
  <tr>
    <td>
      <#-- REGION: intro -->
      Dit is een tekst.
      <#-- END REGION: intro -->
    </td>
  </tr>
</table>

Elke 'region' moet binnen het template een unieke naam hebben (in dit geval 'intro'). We raden aan om de bewerkbare delen zo klein mogelijk te houden, met daarin bijvoorbeeld alleen een paragraaf tekst of andere losse elementen zoals een tabel cel met daarin een afbeelding. Een visuele editor gebruiken om meer complexe code te bewerken (wat we technisch verder niet beperken) brengt risico's met zich mee voor de opmaak wat leiden tot ongewenste resultaten.

Hergebruik

Het is ook mogelijk om (delen van) templates te hergebruiken ('includen') in andere templates. Voorbeelden hiervan zijn bijvoorbeeld headers, footers en banners. Door deze in aparte templates te plaatsen kunnen deze centraal worden bewerkt waardoor ze in alle relevante berichten tegelijk veranderd kunnen worden.

De code voor het includen van een template met ID 1040 ziet er als volgt uit:

<#include "1040">

De bewerkbare delen van 'included' templates worden uitgeschakeld in de Quick editor van het 'buitenste' template. Dit voorkomt dat men per ongeluk wijzigingen aanbrengt die andere templates raakt.

Speciale variabelen

Er is een aantal speciale variabelen beschikbaar voor gebruik in Flowmailer bericht templates:

Variabele Omschrijving Voorbeeld
flowmailer.source.id ID van Source 1234
flowmailer.source.description Omschrijving van Source Webshop
flowmailer.flow.id ID van Flow 5678
flowmailer.flow.description Omschrijving van Flow Order confirmations
receivedMessage.id Flowmailer Message ID 201512161426489b63289c577efc89e2
receivedMessage.sender (SMTP) Sender adres support@flowmailer.com
receivedMessage.from From header Flowmailer Support support@flowmailer.com
receivedMessage.recipient Recipient adres Flowmailer Support support@flowmailer.com
receivedMessage.subject Onderwerp This is a test subject
receivedMessage.headers.* Headers Content-Transfer-Encoding: "quoted-printable"
inPreview In editor preview true

Originele inhoud

Inhoud ophalen

Voor basis 'wrapper'-stijl templates wil men vaak gewoon de hele originele bericht inhoud op een bepaalde plek in het template plaatsen. De volgende code maakt dat mogelijk:

<html>
  <body>
    Plaats hier de originele inhoud:
    <@extractFromOriginal />
  </body>
</html>

Standaard gaat Flowmailer op zoek naar de <body> inhoud in het eerste HTML-part van het bericht. Als deze ontbreekt wordt de inhoud van de eerste Text-part gebruikt, omsloten met <pre> tags.

Elementen ophalen

Het is ook mogelijk om CSS selectors te gebruiken om specifieke onderdelen van het originele bericht op te halen. De meeste CSS3 selectors zoals het W3C ze omschrijft werken. We zullen hier enkele veel gebruikte voorbeelden opnemen:

Selecteer een element met het ID 'eenid':

<@extractFromOriginal selector="#eenid" />


Selecteer de inhoud (tekst?) in de tweede tabelregel, tweede cel, binnen een font tag:

<@extractFromOriginal selector="tr:nth-child(2) td:nth-child(2) font" />


Selecteer de tweede cel van tabelregels die de specifieke tekst 'Veld naam:' bevatten:

<@extractFromOriginal selector="tr:contains(Veld naam:) > td:nth-of-type(2)" />

Element styling (geavanceerd)

Behalve reguliere templates en het hergebruik van originele content, is het ook nog mogelijk om de styling van content on-the-fly aan te passen. Dit wordt vaak toegepast in combinatie met andere templates, bijvoorbeeld om eerst te zorgen dat alle elementen aan de gewenste styling voldoen om vervolgens nog een ander template toe te passen.

We doen dit door de DOM tree te doorlopen met behulp van Freemarkers 'built-ins for nodes'. Elke macro in de onderstaande code zorgt voor een gewijzigde styling, door de attributen te herschrijven.

<#macro h1>
  <h1 style="color: red;"><#recurse></h1>
</#macro>
<#macro a><a href="${.node.@href}" style="color: blue; ><#recurse></a></#macro>
<#macro img></#macro>

<#macro @text>${.node?html}</#macro>
<#macro @element><#t>
<${.node?node_name}<#t>
    <#list .node.@@ as attribute><#t>
        ${" "}${attribute?node_name?html}="${attribute?html}"<#t>
    </#list><#t>
><#t>
<#t>    <#recurse>
<#t></${.node?node_name}>
<#t></#macro>

<html>
  <body>
    <#assign doc=extractNodesFromOriginal()/>
    <#recurse doc>
  </body>
</html>

De bovenstaande code bouwt eigenlijk de hele HTML opnieuw op. Terwijl we dat doen maken we de volgende wijzigingen:

  • Alle h1 teksten zijn nu rood en verliezen alle overige inline styling
  • Alle links zijn nu blauw en behouden daarnaast alleen hun href attribuut
  • Alle afbeeldingen worden verwijderd

Let op! We beschouwen het ontwikkelen van element styling templates als een geavanceerd onderwerp beschouwd en zou door de meeste gebruikers moeten worden vermeden.