Zorg voor je dit artikel leest dat je vertrouwd bent met het principe van CVT formulieren.
We gaan bekijken hoe je zo’n formulier kunt verdelen over 3 afzonderlijke pagina’s, waarbij SPIP het ingewikkelde deel voor zijn rekening neemt: alle reeds ingevoerde gegevens bewaart voor de uiteindelijke verwerking en navigatie tussen de pagina’s mogelijk maakt.
Het skelet van iedere pagina
Iedere pagina is een compleet formulier, waarbij de validatieknop dient om naar de volgende stap te gaan.
Iedere stap is genummerd (vanaf 1) en wordt gedefinieerd door een onafhankelijk skelet dat een autonoom formulier voor de invoergegevens van die pagina implementeert.
Voor de eerste stap maken we een skelet formulaires/inscription_1.html;
voor stap 2 wordt het skelet formulaires/inscription_2.html;
en voor stap 3 wordt het skelet formulaires/inscription_3.html.
Dit is hoe het skelet voor de eerste bladzijde eruit zou kunnen zien:
<div class="formulaire_spip">
[<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>]
[<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>]
[(#ENV{editable})
<form method='post' action='#ENV{action}'><div>
[(#REM) de hidden data die de werking van het formulier bepaalt via de parameter action in de URL ]
#ACTION_FORMULAIRE{#ENV{action},#FORM}
<!-- Hier komen (direct in HTML) de invoervelden van stap 1.
Je kunt ze ook genereren met plugin SAISIES -->
<label>Je email</label>
<input type='text' name='email' value='#ENV{email}' />
<input type="submit" class="submit" value="<:pass_ok:>" />
</div></form>
]
</div>
Binnen ieder skelet geeft #ENV{_etape} de stap door en #ENV{_etapes} het aantal stappen. Hiermee kan bijvoorbeeld de vordering aan de gebruiker worden getoond:
<div class="formulaire_spip formulaire_inscription formulaire_#FORM formulaire_#FORM_#ENV{_etape}">
<h3>Inschrijving #ENV{_etape} / #ENV{_etapes}: je emailgegevens</h3>
...
Op iedere pagina bevat #ENV alle reeds eerder ingevoerde waardes. Dit kan bijvoorbeeld handig zijn om een bepaalde invoer voor te stellen die is gebaseerd op een eerdere invoer.
Op iedere pagina kun je ook knoppen aanbieden om tussen de pagina’s van het formulier te navigeren. Om bijvoorbeeld terug te gaan naar een vorige stap geef je het attribuut name van de knop de waarde _retour_etape_n, waarbij n die stap is:
<p class="boutons">
<input type="submit" class="submit" name="_retour_etape_2" value="<:retour:>" />
</p>
Het mag ook een stap vooruit zijn, maar de gebruiker kan die stap pas maken als de invoer op de pagina zelf volledig en foutloos is! Anders zal een foutmelding worden weergegeven, samen met de huidige invoerpagina.
Laden en declareren van de invoerstappen
Het declareren van de stappen (ofwel de pagina’s) gebeurt met de functie charger() van je CVT formulier.
De functie charger() is dezelfde als die van een conventioneel CVT formulier: ze retourneert een tabel met alle invoervelden van het totale formulier (die van alle stappen, alsof het om één enkele invoerpagina gaat).
Maar daarnaast moet de functie aangeven dat het formulier uit meerdere pagina’s bestaat. Dat gebeurt door het meesturen van ’_etapes’ wat het aantal pagina’s aangeeft.
In ons voorbeeld:
function formulaires_inscription_charger_dist() {
return array (
'email' => '', // stap 1
'naam' => '', // stap 2
'voornaam' => '',
'week' => 0, // stap 3
'_etapes' => 3);
}
Het is deze waarde _etapes die ervoor zorgt dat SPIP rekening gaat houden met meerder pagina’s.
De invoer van iedere stap verifiëren
De verificatie van de ingevoerde gegevens heeft een bijzonderheid. In plaats van een enkele functie verifier() (zoas in een conventioneel formulier), moeten we een functie verifier() per invoerpagina hebben. Deze worden genummerd vanaf 1 zoals bij de skeletten van de verschillende pagina’s.
formulaires_inscription_verifier_1_dist verifieert alleen de eerste stap;formulaires_inscription_verifier_2_dist verifieert stap 2;formulaires_inscription_verifier_3_dist verifieert stap 3.
enz.
Binnen deze functies maakt het oproepen van _request het mogelijk alle vanaf stap 1 ingevoerde gegevens tot aan de huidige te verifiëren.
De huidige stap en het rotale aantal stappen kunnen worden gevonden met request(’_etape’) en request(’_etapes’) om bijvoorbeeld bepaalde code te delen.
Na een pagina n roept SPIP functies voor de verificatie op vanaf stap 1 tot n (dit om eventuele onrechtmatig gebruik tegen te gaan). Bij een fout keert de gebruiker vanzelf terug op de eerste pagina waarop een fout werd ontdekt.
Is alles in orde, dan roept SPIP de volgende stap op, behalve als de gebruiker op de laatste pagina is. In dat geval roept het de functie traiter().
Verwerking van de invoer
Pas wanneer alle gegevens juist zijn ingevoerd wordt deze functie aangeroepen.
Met de functie _request kan de volledige invoer worden benaderd, net als met een formulier van één pagina.
Deze functie is dus identiek en heeft de klassieke benaming (in ons voorbeeld formulaires_inscription_traiter_dist()).
Vergeet niet...
- Alle voordelen van een enkelvoudig formulier zijn ook hier van toepassing. Je kunt dus een <div class='ajax'> om het formulier plaatsen.
- Je kunt de weergave van het formulier bij een bepaalde stap (bijvoorbeeld stap 2) laten beginnen. Daarvoor geef je de parameter "_etape=2" aan de context door (bijvoorbeeld via de URL.
In dit geval worden de pagina’s 1 en 2 geverifieerd en wordt als volgende stap 3 weergegeven. Anders wordt de eerste pagina met een fout getoond.