Om ervoor te zorgen dat ingevulde formulieren de data bevat die het zou moeten bevatten kun je de data na het versturen van het formulier valideren. Voor verschillende soorten velden zijn verschillende soorten validators beschikbaar. Kijk voor een volledig overzicht op deze pagina.

De validatie van het formulier moet pas gedaan worden als het formulier ook daadwerkelijk verzonden is. Hiervoor gebruiken we in ons index-bestand in de map 'mail' de volgende code:

{% if param.postAll != empty %} {# Kijkt of het formulier verzonden is en of de velden zijn ingevuld #}
    {% set v = validate
        .requireToken(false)
        .setRetention(0)             
        .setId('aanmeldenMailchimp') 
        .setType('post')
    %}
{% else %}
    {# Hier de code voor het formulier #}
{% endif %}

De bovenstaande velden initiëren de eerste instellingen voor de validatie. Voor het voorbeeld zetten we de waarde requireToken() op 'false'. Het enige wat we nu nog moeten doen is het instellen van de velden die gecontroleerd moeten worden. Dat doen we met de volgende code, die onder de regel .setType('post') komt:

        .field('voornaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('tussenvoegsel', ['maxlength(10)','isempty'], 'Dit tussenvoegsel is te lang'|t)
        .field('achternaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('email', 'mail', 'Vul een geldig e-mailadres in'|t)

Nadat alle velden zijn gecontroleerd kunnen we aan de hand van de variabele v gaan kijken of we door kunnen met het verwerken van het formulier. Dat doen we door de voglende code:

    {% if v.complete and not v.error %}

        {# Hier de code voor het invoegen van het adres in MailChimp en het versturen van de e-mail #}

    {% else %}

        {# Hier de foutafhandeling voor als er een error te vinden is in v #}
        <div class="alert alert-rood">
            <b>{{ 'Los het volgende op:'|t }}</b>
            <ul>
                {% for error in v.getMessages %}
<li>{{ error }}</li>
                {% endfor %}
            </ul>
        </div>

    {% endif %}

De volledige code na stap twee ziet er dan als volgt uit:

{% if param.postAll != empty %} {# Kijkt of het formulier verzonden is en of de velden zijn ingevuld #}
    {% set v = validate
        .requireToken(false)
        .setRetention(0)             
        .setId('aanmeldenMailchimp') 
        .setType('post')
        .field('voornaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('tussenvoegsel', ['maxlength(10)','isempty'], 'Dit tussenvoegsel is te lang'|t)
        .field('achternaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('email', 'mail', 'Vul een geldig e-mailadres in'|t)
    %}
    {% if v.complete and not v.error %}

        {# Hier de code voor het invoegen van het adres in MailChimp en het versturen van de e-mail #}

    {% else %}

        {# Hier de foutafhandeling voor als er een error te vinden is in v #}
        <div class="alert alert-rood">
            <b>{{ 'Los het volgende op:'|t }}</b>
            <ul>
                {% for error in v.getMessages %}
<li>{{ error }}</li>
                {% endfor %}
            </ul>
        </div>

    {% endif %}
{% else %}
    {# Hier de code voor het formulier #}
{% endif %}

Nu we de validatie van ons formulier op orde hebben is het tijd om de code te schrijven voor het toevoegen van het e-mailadres aan MailChimp. Om dit te bewerkstelligen is het nodig dat je de beschikking hebt over een MailChimpaccount en -API-key, zodat nodum weet met welk account er gewerkt moet worden. Als je nog geen MailChimpaccount hebt kun je die aanmaken op de site van MailChimp.

API-key ophalen

Wanneer je je account hebt aangemaakt kun je beginnen met het aanmaken van Lists en Templates binnen MailChimp, dit voorbeeld zal daar echter niet op ingaan. Het is voor het gebruik van de MailChimp-API in nodum verplicht om een API-key op te geven in de instellingen van het project waar je mee werkt. Die key haal je als volgt op binnen MailChimp: Login op je MailChimp-account, klik in het linkermenu op je gebruikersnaam (1) en daarna op Account (2). Binnen deze settings kies je voor Extras (3) en vervolgens voor Api keys(4). Hier heb je de mogelijkheid om jouw unieke API-key aan te maken. Druk op Create A Key (5) en de API-key wordt automatisch gegenereerd.

API Key toevoegen
Deze Mailchimp Key voeg je toe aan de Algemene instellingen van je project in de module Instellingen in de meest linker kolom van de nodum console.

[mailchimp]
    apikey="..."

Mailchimp gebruiken
Vervolgens gaan we in het bestand 'index.twig' de juiste code plaatsen om de gebruiker in te schrijven op de juiste List in MailChimp. Dit doen we door de API van MailChimp aan te roepen met {% api.MailChip_* %}, waar op de plaats van de '*' de te gebruiken methode komt. Dat is in dit geval de methode SetSubscriber en die heeft de volgende opbouw:
api.MailChimp_SetSubscriber(string ListID, array/string merge_fields)
Het ListID is op te halen in de Settings van je List, een uitgebreide uitleg hierover is hier te vinden. De merge_fields vind je eveneens in de Settings en in ons geval zijn dat alleen 'voornaam' (FNAME) en 'achternaam' (LNAME). Om de juiste gegevens van de gebruiker in de methode mee te geven plaatsen we deze code direct onder {% if v.complete and not v.error %}:

    {% if param.post('tussenvoegsel') %}
        {% set achternaam = param.post('tussenvoegsel')|trim ~ ' ' ~ param.post('achternaam')|trim %}
    {% else %}
        {% set achternaam = param.post('achternaam')|trim %}
    {% endif %}

    {% set fields = {FNAME: param.post('voornaam')|trim, LNAME: achternaam } %}
    {% set data = {email_address: param.post('email'), merge_fields: fields} %}

In bovenstaande code kijken we eerst of er een tussenvoegsel is opgegeven. Is dit het geval, combineer dan het tussenvoegsel met de achternaam tot de variabele achternaam. Anders wordt de variabele achternaam gevuld met de waarde die in het veld achternaam staat. Daarna wordt de variabele data aangemaakt, waarin de merge_fields worden opgeslagen.
Nu we het ListID, het e-mailadres en de naam van de gebruiker hebben opgeslagen kunnen we verdergaan met het aanbieden van deze gegevens aan de API van MailChimp volgens de methode die hierboven staat. Om te controleren of de call succesvol is uitgevoerd zetten we de methode in een if-else-blok en met de ingevulde gegevens ziet dat er als volgt uit: (Deze code komt onder het bovenstaande codeblok)

    {% if api.MailChimp_SetSubscriber('3a5349c6dd', data) %}
        {# Call gelukt #}
    {% else %}
        {# Call mislukt, hier de foutafhandeling #}
        <div class="alert alert-rood">
            Oh nee. Er is iets fout gegaan in de inschrijving op de nieuwsbrief. Stuur een e-mail naar admin@project.nl en vraag of je handmatig op de lijst gezet kan worden. Je kunt het uiteraard ook nog een keer opnieuw proberen.
        </div>
    {% endif %}

Dit betekent dat onze code in 'index.twig' er als volgt uitziet:

{% if param.postAll != empty %} {# Kijkt of het formulier verzonden is en of de velden zijn ingevuld #}
    {% set v = validate
        .requireToken(false)
        .setRetention(0)             
        .setId('aanmeldenMailchimp') 
        .setType('post')
        .field('voornaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('tussenvoegsel', ['maxlength(10)','isempty'], 'Dit tussenvoegsel is te lang'|t)
        .field('achternaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('email', 'mail', 'Vul een geldig e-mailadres in'|t)
    %}
    {% if v.complete and not v.error %}

        {% if param.post('tussenvoegsel') %}
            {% set achternaam = param.post('tussenvoegsel')|trim ~ ' ' ~ param.post('achternaam')|trim %}
        {% else %}
            {% set achternaam = param.post('achternaam')|trim %}
        {% endif %}

        {% set fields = {FNAME: param.post('voornaam')|trim, LNAME: achternaam } %}
        {% set data = {email_address: param.post('email'), merge_fields: fields} %}

        {% if api.MailChimp_SetSubscriber('3a5349c6dd', data) %}
            {# Call gelukt #}
        {% else %}
            {# Call mislukt, hier de foutafhandeling #}
        {% endif %}       

    {% else %}

        {# Hier de foutafhandeling voor als er een error te vinden is in v #}
        <div class="alert alert-rood">
            <b>{{ 'Los het volgende op:'|t }}</b>
            <ul>
                {% for error in v.getMessages %}
<li>{{ error }}</li>
                {% endfor %}
            </ul>
        </div>
        {# Hier nogmaals de code voor het formulier, zodat de gebruiker direct opnieuw kan invoeren #}
    {% endif %}
{% else %}
    {# Hier de code voor het formulier #}
{% endif %}

Vergeet niet dat je wel een geldige API-key van MailChimp moet hebben ingevoerd in de algemene instellingen van je project, anders weet nodum niet met welk account hij moet communiceren.
Als de call gelukt is willen we de gebruiker notificeren van de inschrijving op de MailChimplijst. Dit doen we door een visuele weergave op het scherm en het versturen van een e-mail vanuit nodum. Dit alles staat in stap 4.

Met nodum is het standaard mogelijk om een e-mail te versturen als je beschikt over een Mandrill- of Mailgunaccount beschikt. Voor beide mailproviders geldt dat je (wederom) moet beschikken over een geldige API-key en deze moet invoeren in de algemene instellingen van je project. De key kun je toevoegen onder [mailgun] of [mandrill], vergeet niet om de juiste mailprovider te selecteren onder het kopje [general] in de algemene instellingen.

Mailen in nodum Voor het mailen in nodum is er, naast de API-key en de juiste mailprovider in de instellingen, alleen nog het e-mailtemplate nodig van waaruit de mail verstuurd gaat worden. Dit template kan gemaakt worden in de standaardmap E-mail. Voor dit voorbeeld maken we hier een nieuw bestand aan genaamd 'bevestigingmailchimp'. Het enige wat we hieronder laten zien is dat de aanmelding op de nieuwsbrief geslaagd is. Dat doen we met de volgende code.

Beste {{ naam }},<br>
<br>
Dank voor het inschrijven op de nieuwsbrief van nodum! We zullen je op het e-mailadres {{ email }} nu op de hoogte houden van de laatste ontwikkelingen van ons platform, de markt en de wereld!<br>
Veel plezier!<br>
Groeten,<br>
Het nodum-team.

Hierboven kun je uiteraard ieder zelfbedacht bericht neerzetten. Let wel even op de variabelen {{ naam }} en {{ e-mail }}, deze vullen we met het 'mail'-object. Dit object bestaat uit de volgende code:
mail.send(string toMailAddr, string toName, string subject, string templateName, array mergeVars, mixed attachments)
We hebben in dit voorbeeld niet te maken met bijlages, dus de attachments blijven leeg. Het e-mailadres waar naartoe gemaild moet worden is bekend, de naam van de gebruiker ook. Het onderwerp kunnen we zelf verzinnen en de templatenaam is gelijk aan die we hierboven hebben aangemaakt. De mergeVars zijn de enige gegevens die we nog aan moeten maken. Hierin komen de variabelen 'naam' en 'e-mail', zodat we die in ons template kunnen gebruiken.

    {% set name      = param.post('voornaam') ~ ' ' ~ achternaam %}
    {% set address   = param.post('email') %}
    {% set mergeVars = {email: address, naam: name}  %}

Met deze gegevens gaan we de mail verzenden! Uiteraard gebruiken we hier weer een if-else-blok om te kijken of alles goed gegaan is.

    {% if mail.send(address, name, 'Bevestiging inschrijving nieuwsbrief nodum', 'bevestigingmailchimp', mergeVars) %}
        {# Inschrijving op lijst is gelukt en de mail is verstuurd, dus tijd voor feedback #}
        <div class="alert alert-groen">
            Gelukt! Er is een bevestigingsmail naar je toegestuurd en vanaf vandaag ontvang je het laatste nieuws omtrent nodum!
        </div>
    {% else %}
        {# Hier de foutafhandeling voor wanneer mail niet verstuurd kan worden #}
        <div class="alert alert-oranje">
            Oh oh. Er is iets fout gegaan in het verzenden van de bevestigingsmail. Maar maak je geen zorgen, je bent wel ingeschreven op de nieuwsbrief van nodum! Je wordt dus op de hoogte gehouden van het laatste nieuws omtrent het platform en de ontwikkelingen in de markt en de wereld!
        </div>
    {% endif %}

Wanneer we deze code implementeren in ons bestand 'index.twig' zijn we klaar om de wereld te laten inschrijven op onze nieuwsbrief! De volledige code vind je hieronder:

{% if param.postAll != empty %} {# Kijkt of het formulier verzonden is en of de velden zijn ingevuld #}
    {% set v = validate
        .requireToken(false)
        .setRetention(0)             
        .setId('aanmeldenMailchimp') 
        .setType('post')
        .field('voornaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('tussenvoegsel', ['maxlength(10)','isempty'], 'Dit tussenvoegsel is te lang'|t)
        .field('achternaam', 'alpha', 'Vul alleen hoofd- of kleine letters in.'|t)
        .field('email', 'mail', 'Vul een geldig e-mailadres in'|t)
    %}
    {% if v.complete and not v.error %}

        {% if param.post('tussenvoegsel') %}
            {% set achternaam = param.post('tussenvoegsel')|trim ~ ' ' ~ param.post('achternaam')|trim %}
        {% else %}
            {% set achternaam = param.post('achternaam')|trim %}
        {% endif %}

        {% set fields = {FNAME: param.post('voornaam')|trim, LNAME: achternaam } %}
        {% set data = {email_address: param.post('email'), merge_fields: fields} %}

         {% if api.MailChimp_SetSubscriber('3a5349c6dd', data) %}
            {# Call gelukt #}
            {% set name      = param.post('voornaam') ~ ' ' ~ achternaam %}
            {% set address   = param.post('email') %}
            {% set mergeVars = {email: address, naam: name}  %}
            {% if mail.send(address, name, 'Bevestiging inschrijving nieuwsbrief nodum', 'bevestigingmailchimp', mergeVars) %}
                {# Inschrijving op lijst is gelukt en de mail is verstuurd, dus tijd voor feedback #}
                <div class="alert alert-groen">
Gelukt! Er is een bevestigingsmail naar je toegestuurd en vanaf vandaag ontvang je het laatste nieuws omtrent nodum!
                </div>
            {% else %}
                {# Hier de foutafhandeling voor wanneer mail niet verstuurd kan worden #}
                <div class="alert alert-oranje">
Oh oh. Er is iets fout gegaan in het verzenden van de bevestigingsmail. Maar maak je geen zorgen, je bent wel ingeschreven op de nieuwsbrief van nodum! Je wordt dus op de hoogte gehouden van het laatste nieuws omtrent het platform en de ontwikkelingen in de markt en de wereld!
                </div>
            {% endif %}
        {% else %}
            {# Call mislukt, hier de foutafhandeling #}
            <div class="alert alert-rood">
                Oh nee. Er is iets fout gegaan in de inschrijving op de nieuwsbrief. Stuur een e-mail naar admin@project.nl en vraag of je handmatig op de lijst gezet kan worden. Je kunt het uiteraard ook nog een keer opnieuw proberen.
            </div>
        {% endif %}       

    {% else %}

        {# Hier de foutafhandeling voor als er een error te vinden is in v #}
        <div class="alert alert-rood">
            <b>{{ 'Los het volgende op:'|t }}</b>
            <ul>
                {% for error in v.getMessages %}
<li>{{ error }}</li>
                {% endfor %}
            </ul>
        </div>
        {# Hier nogmaals de code voor het formulier, zodat de gebruiker direct opnieuw kan invoeren #}

    {% endif %}
{% else %}
    {# Hier de code voor het formulier #}
{% endif %}