Bijvoorbeeld CVT formulieren

Een contactformulier in 4 stappen

Het maken van formulieren is in SPIP een relatief eenvoudige aangelegenheid. We tonen het met een simpel, concreet voorbeeld.

CVT betekent Charger-Vérifier-Traiter, ofwel laden-verifiëren-verwerken en is een programmeermethode voor formulieren in SPIP.

Stap 1: We maken het skelet voor het formulier

In de submap formulaires/ van je map squelettes/ zet je een bestand met de naam contact.html dat de HTML voor het formulier gaat bevatten. Bijvoorbeeld:

<form action='#ENV{action}' method='post'>
	#ACTION_FORMULAIRE{#ENV{action}}
	<label>Je emailadres</label>
	<input type='text' name='email' value='#ENV{email}' />
	<br />
	<label>Je bericht</label>
	<textarea name='message'>#ENV{message}</textarea>
	<input type='submit' name='ok' value='ok' />
</form>

Zoals je ziet bevat het slechts enkele opvallende onderdelen:

  • het attribuut action van de tag <form> bevat #ENV{action} wat de URL is waarnaar het formulier zal worden verzonden;
  • #ACTION_FORMULAIRE{#ENV{action}} vertelt SPIP de gegevens te verzenden volgens de CVT methode en deze gegevens eventueel via de URL door te geven. Vanaf SPIP 2.1 is #ENV{action} In feite nutteloos, omdat het de standaardmethode is geworden;
  • elke input, textarea of select bevat de waarde #ENV{xxx} waarbij xxx overeen komt met het attribuut name.

In dit stadium kan het formulier al in een skelet worden weergegeven met het baken #FORMULAIRE_CONTACT of direct in de tekst van een artikel met <formulaire|contact>. Je kunt het formulier testen en aanpassen zoner één regel PHP te hebben geschreven.

Maar druk je op de knop OK, dan gebeurt er niet en je vindt je invoer nergens terug.

Stap 2: De functie laden

We gaan nu aangeven welke velden de bezoeker kan invullen.

Maak hiervoor een bestand contact.php in de submap formulaires/, naast je skelet contact.html, waarin je de volgende code opneemt:

<?php

function formulaires_contact_charger_dist(){
	$valeurs = array('email'=>'','message'=>'');
	
	return $valeurs;
}
?>

Wat doet deze code?

Het declareert de functie charger van het formulier contact in de map formulaires hierna genoemd formulaires_contact_charger.
De suffix _dist duidt aan dat het om een functie (charger) gaat die standaard voor dit formulier moet worden geladen, maar ze kan eventueel worden aangepast (zie hiervoor programmer.spip.org).

Deze functie beschrijft in de variabele $valeurs de invoervelden van het formulier en voor ieder veld de standaardwaarde.
De functie formulaires_contact_charger_dist verstuurt dus deze lijst van velden.

Test het formulier opnieuw: vul je de velden in en op de OK knop klikt, zie je dat de gegevens nu in het formulier blijven staan (maar verder gebeurt er nog niets).

In dit voorbeeld zijn alle velden standaard leeg. We kunnen dit verbeteren door automatisch het emailveld in te vullen wanneer de bezoeker is aangemeld.
we doen het met de volgende code:

function formulaires_contact_charger_dist(){
	$valeurs = array('email'=>'','message'=>'');
	if (isset($GLOBALS['visiteur_session']['email']))
		$valeurs['email'] = $GLOBALS['visiteur_session']['email'];
	return $valeurs;
}

Test je nu het formulier, dan zul je (omdat je bent aangemeld) zien:

  • dat het veld voor het emailadres al is ingevuld;
  • dat de ingevoerde waardes worden bewaard na validatie.

Stap 3: De ingevoerde gegevens verifiëren

Voordat we de ingevoerde gegevens willen toepassen, gaan we eerst controleren of die gegevens wel correct zijn.

We gaan de volgende voorwaarden stellen:

  • de velden email en message zijn verplicht;
  • het emailadres moet worden gevalideerd.

Om de invoer te verifiëren gaan we de functie formulaires_contact_verifier_dist opnemen (in hetzelfde model als de functie charger) en ook in het bestand contact.php:

function formulaires_contact_verifier_dist(){
	$erreurs = array();
	// verifieer of de verplichte velden zijn ingevoerd:
	foreach(array('email','message') as $obligatoire)
		if (!_request($obligatoire)) $erreurs[$obligatoire] = 'Dit veld is verplicht';
	
	// verifieer de geldigheid van het emailadres:
	include_spip('inc/filtres');
	if (_request('email') AND !email_valide(_request('email')))
		$erreurs['email'] = 'Dit emailadres is niet geldig';

	if (count($erreurs))
		$erreurs['message_erreur'] = 'Je invoer bevat fouten!';
	return $erreurs;
}

Opmerking: het gebruik van _request() wordt uitgelegd op de site programmer.spip.org

De functie verifier zendt een lijst van velden met fouten, met voor ieder veld de bijbehorende foutboodschap.

Op dit punt zie je, wanneer je het formulier test, nog geen enkel verschil: je formulier contact.html geeft nog geen foutboodschappen. We moeten hun plaats namelijk nog op het formulier aangeven:

[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
<form action='#ENV{action}' method='post'>
	#ACTION_FORMULAIRE{#ENV{action}}
	<label>Je emailadres</label>
	[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
	<input type='text' name='email' value='#ENV{email}' />
	<br />
	<label>Je bericht</label>
	[<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
	<textarea name='message'>#ENV{message}</textarea>
	<input type='submit' name='ok' value='ok' />
</form>

Merk op:

  • de weergave van de algemene foutboodschap die wordt verzonden door de functie verifier:
    [<p class='reponse_formulaire reponse_formulaire_erreur'>(#ENV*{message_erreur})</p>]
  • de foutboodschappen vóór ieder veld:
    [<span class='erreur_message'>(#ENV**{erreurs}|table_valeur{email})</span>].

Test je formulier nu opnieuw met een onjuist emailadres of laat een veld leeg: de interactie met je bezoeker is een feit!

Stap 4: Verwerken!

Wanneer de functie verifier geen fout verzendt, zal SPIP automatisch de functie traiter starten. Deze functie formulaires_contact_traiter_dist (nog altijd in het bestand contact.php moet een mail naar de webmaster gaan verzenden:

function formulaires_contact_traiter_dist(){
	$envoyer_mail = charger_fonction('envoyer_mail','inc');
	$email_to = $GLOBALS['meta']['email_webmaster'];
	$email_from = _request('email');
	$sujet = 'Contactformulier';
	$message = _request('message');	
	$envoyer_mail($email_to,$sujet,$message,$email_from);
	return array('message_ok'=>'Je bericht werd verzonden. We zorgen zo spoedig mogelijk voor een antwoord!');
}

Je ziet dat de functie traiter geen enkele verificatie doet: dat is allemaal al gebeurd. De functie wordt immers pas aangeroepen wanneer er geen fouten zijn gevonden.

De functie traiter verzend een bevestiging, « message_ok », in tabelvorm. Net als voor de foutboodschappen, moeten we hier een plaats voor reserveren op ons formulier. Dat doen we alsvolgt:

[<p class='formulaire_ok'>(#ENV*{message_ok})</p>]
[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
[(#EDITABLE|oui)
	<form action='#ENV{action}' method='post'>
		#ACTION_FORMULAIRE{#ENV{action}}
		<label>Je emailadres</label>
		[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
		<input type='text' name='email' value='#ENV{email}' />
		<br />
		<label>Je bericht</label>
		[<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
		<textarea name='message'>#ENV{message}</textarea>
		<input type='submit' name='ok' value='ok' />
	</form>
]

Merk op:

  • de succesboodschap aan het begin:
    [<p class="formulaire_message">(#ENV*{message_ok})</p>]
  • de conditionele weergave van het formulier in functie van het baken #EDITABLE: na de invoer is het beter om de invoer niet meer te tonen, maar wel de succesboodschapaprès la saisie. #EDITABLE zorgt daar voor.

Tip: In sommige gevallen wil je een lus (BOUCLE) in het formulier opnemen (om bijvoorbeeld een selectie uit de database voor te stellen). Het gebruik van #EDITABLE en deze lus genereert een fout. De oplossing is om een lus CONDITION Toe te voegen zoals hieronder getoond:

    [<p class='formulaire_ok'>(#ENV*{message_ok})</p>]
    [<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
    <BOUCLE_editable(CONDITION){si #ENV{editable}|oui}>
            <form action='#ENV{action}' method='post'>
                    #ACTION_FORMULAIRE{#ENV{action}}
                   <BOUCLE_article(ARTICLES}{0,1}>#TITRE</BOUCLE_article>
             <label>Je emailadres</label>
                    [<span class='erreur'>(#ENV**{erreurs}|table_valeur{email})</span>]
                    <input type='text' name='email' value='#ENV{email}' />
                    <br />
                    <label>Je bericht</label>
                    [<span class='erreur'>(#ENV**{erreurs}|table_valeur{message})</span>]
                    <textarea name='message'>#ENV{message}</textarea>
                    <input type='submit' name='ok' value='ok' />
            </form>
    </BOUCLE_editable>

Klaar! Je kunt het contactformulier gebruiken.

De bonus

Wil je de interactie wat versnellen en niet steeds opnieuw de gehele pagina laden?

Dat kan dankzij de ajax functionaliteit. Het resultaat is een snellere interactie, maar de implementatie vraagt normaal veel tijd en testen. In SPIP kun je dankzij de CVT-methode je formulieren vrij eenvoudig omzetten in ajax.

je moet daarvoor het formulier in een div met class=ajax insluiten:

<div class='ajax'>
#FORMULAIRE_CONTACT
</div>

En dat is alles!

Nog een stap verder

-  Het formulier in dit voorbeeld ziet er niet geweldig uit. Voor een meer esthetisch resultaat kun je de aanbevelingen in Structure HTML des formulaires de SPIP op al je formulieren toepassen;
-  Alles over de functie charger(): De functie charger() van een CVT-formulier
-  Alles over de functie verifier(): De functie verifier() van een CVT-formulier
-  Alles over de functie traiter(): De functie traiter() van een CVT-formulier

Auteur Hanjo Gepubliceerd op: Aangepast: 21/03/23

Vertalingen: català, English, Español, français, Nederlands