Meer met Plate

Hoe maak je (contact)formulieren?

In een recente update is het formulier systeem van Plate geüpdatet, en bij deze nieuwe update hoort natuurlijk een tutorial waarin wordt uitgelegd wat de beste manier is om formulierelementen te maken. Hierbij zullen we kijken naar verschillende veldtypes, zoals een korte tekst, een lange tekst, een checkbox en een uploadveld. Uiteraard zit er een standaard formulierelement in Plate, deze tutorial helpt om inzicht te krijgen in hoe deze is opgebouwd en hoe je je eigen formulieren kunt maken.

Content model

Zoals een goede Plate gewoonte is, denken we eerst het contentmodel uit voor dit element. We kiezen voor één contenttype dat het formulier zelf representeert, met velden voor bijvoorbeeld de succes pagina en het emailadres waar berichten van dit formulier naartoe moeten worden gestuurd. Daarnaast zal het formulier contenttype ook een referentie bevatten naar de formuliervelden, zodat de sitebewerker makkelijk en onbeperkt velden kan toevoegen aan een formulier.

Stap 1: Contactformulier contenttype

Allereerst maken we een contenttype aan voor het Contactformulier.

Stap 2: Formuliervelden contenttype

Vervolgens maken we een contenttype aan voor de formuliervelden. Dit contenttype gaan we straks gebruiken als referentie in het Contactformulier, dus we verbergen dit content type in het Toevoegen-menu.

Stap 3: Formulierveld contentvelden

Nu voegen we de volgende velden toe aan het Formulierveld contenttype:

Naam (Korte tekst, verplicht)
Veldtype (Dropdown, verplicht) Met de volgende mogelijke waardes
- Korte tekst [[text]]
- Lange tekst [[textarea]]
- Checkbox [[checkbox]]
- Bestand [[file]]
Verplicht (toggle, niet verplicht)

Opmerking: als je bij een dropdown veld achter een vooringestelde waarde nog een extra waarde tussen [[ ]] zet, dan ziet de sitebewerker de eerste waarde (bijvoorbeeld "Korte tekst"), terwijl je in je template de waarde krijgt die tussen de [[ ]] staat (bijvoorbeeld "text").

Opmerking 2: let erop dat het 'verplicht' veld een booleaanse waarde (true/false) moet terug geven. Vandaar dat gebruik gemaakt wordt van het true/false keuzeveld.

Stap 4: Contactformulier contentvelden

Nu voegen we de volgende velden toe aan het Contactformulier contenttype:

Formuliervelden (Referentie naar formuliervelden, tenminste 1)
Doel e-mailadres (Korte tekst, met reguliere expressie validatie voor email)
Verzendknoptekst (Korte tekst, verplicht)
Succes pagina (Link, niet verplicht)

Themabestanden

Nu het contentmodel klaarstaat kunnen we beginnen met het maken van de themabestanden voor de elementen. Deze uploaden we natuurlijk met behulp van de Plate Themetool.

Stap 5: Contactformulier themabestand

We beginnen met het themabestand voor het Contactformulier zelf.

# Locatie: contact_forms/_contact_form.plate {% include "contact_forms/contact_form_errors" %} {% form for: contact_form, to: contact_form.email, success_url: contact_form.success_page_link %} {% for field in contact_form.field_lines %} {% include field %} {% endfor %}

{% endform %}

Allereerst wordt een bestandje geinclude, waar de eventuele validatie errors worden weergegeven.

Vervolgens is er een form tag aanwezig. Deze tag creëert een <form> element. In deze tag geven we wat argumenten mee:

for: contact_form. Hier zeggen we tegen Plate welk object het formulier representeert. Dit wordt bijvoorbeeld gebruikt om de url naar de pagina van dit formulier te achterhalen.
to: contact_form.email. Dit zorgt ervoor dat berichten van dit formulier worden verstuurd naar een emailadres dat door de sitebewerker is ingevuld.
success_url: contact_form.succes_page_link. Dit zorgt ervoor dat als het formulier wordt verstuurd, de bezoeker naar een pagina wordt doorgestuurd die door de sitebewerker is ingevuld. Als je dit weglaat, of de sitebewerker niets invult, dan blijft de bezoeker op dezelfde pagina na het versturen.

Vervolgens wordt met een forloop ieder formulierveld geinclude. Later zien we wat voor themabestand deze hebben.

Tenslotte wordt nog een <input> ingevoegd, met het type "submit". Dit is dus de verzendknop bij het formulier. De value van deze html-tag (oftewel de tekst op de knop) wordt ook weer uit het contact_form object gehaald.

Stap 6: Contactformulier errors themabestand

In de vorige stap zagen we dat er een contact_form_errors bestandje werd geinclude. Dit bestandje ziet er als volgt uit:

# Locatie: contact_forms/_contact_form_errors.plate {% if request.flash.alert %}

{{ error_msg }}

{% endif %}

Eerst wordt er gecontroleerd of er iets in "request.flash.alert" zit. Het request object bevat allerlei informatie, waaronder een "flash" object. Dit "flash" object bevat berichten die door de Plate server worden ingesteld als bijvoorbeeld een formulier nog validatie errors bevat, of dat een formulier succesvol is verzonden.

Als er een validatie error wordt gedetecteerd tijdens het opsturen van een formulier, dan wordt er een bericht in "request.flash.alert" ingesteld. Dit is een standaard bericht, of het kan worden ingesteld in de form tag.

Als er een error bericht is gevonden is er blijkbaar iets fout, dus dan wordt er een <p> object (met rode tekst) gemaakt, waarin de foutmelding wordt weergegeven door middel van "{{ request.flash.alert }}".

Vervolgens worden alle errors uit "request.flash.errors" uitgelezen door middel van een forloop, en weergegeven in een lijst.

Stap 7: Formulierveld themabestand

Ten slotte moet er nog een themabestand worden gemaakt, dat ervoor zorgt dat de formuliervelden op de juiste manier worden weergegeven en geregistreerd in Plate.

# Locatie: form_fields/_form_fields.plate

{{ form_field.name }} {{ form_field.name | form_input_name | html_input: form_field.type }}

{% register_form_field form_field.name, required: form_field.required %}

Dit themabestand laat eerst een <label> met de naam van het formulierveld.

Vervolgens worden er twee filters gebruikt om een <input> tag te maken. Allereerst wordt het "form_input_name" filter gebruikt, met als argument "form_field.name". Dit zorgt ervoor dat de naam van een formulierveld wordt omgezet in iets dat door Plate kan worden begrepen als input naam. Deze gegenereerde input naam wordt gebruikt als argument voor de "html_input" filter.

Dit filter zorgt ervoor dat er een <input> tag wordt gemaakt met de juist naam. Als extra argument wordt "form_field.type" meegegeven. Dit argument kan bijvoorbeeld "text", "textarea", of "file" zijn, zoals gedefinieerd in stap 3.

Ten slotte wordt er de "register_form_field" aangeroepen. Deze tag maakt geen html code aan, maar zorgt ervoor dat Plate weet dat het veld met de naam "form_field.name" wordt opgestuurd door dit formulier.

Hiermee wordt enerzijds voorkomen dat kwaadwillenden op de site zomaar willekeurig extra velden kunnen toevoegen met ongewenste uitwerkingen. Anderzijds kan hier ook worden doorgegeven of dit veld verplicht is om in te vullen, wat gedaan wordt met "required: form_field.required". Als dit veld dan niet wordt ingevuld maar wel required was, dan wordt er een validatie error in het "request.flash.errors" object toegevoegd. (Deze kan dan weer worden gebruikt zoals we zagen in stap 6.

Testen

Nu we het contentmodel hebben aangemaakt in het dashboard, en de themabestanden hebben toegevoegd, kunnen we het formulier object toevoegen in de bewerkmodus.