De functie traiter() van een CVT-formulier

Hoe definieer je de functie

De functie traiter() van een formulier XXX (wat in een skelet wordt weergegeven met #FORMULAIRE_XXX) wordt gedefinieerd in het bestand formulaires/xxx.php of in het bestand formulaires/xxx/traiter.php. De map formulaires/ moet zich bevinden in de map van een plugin, of in de map squelettes/.

De functie moet worden genoemd function formulaires_xxx_traiter_dist(). De suffix _dist laat een ontwikkelaar toe zijn gedrag aan te passen door het maken van een functie function formulaires_xxx_traiter().

De argumenten van de functie

Net als de functies charger() en verifier() ontvangt de functie traiter() automatisch in dezelfde volgorde de waarde van ieder argument dat aan het baken #FORMULAIRE_XXX werd doorgegeven. Door bijvoorbeeld te schrijven:

#FORMULAIRE_XXX{#ID_ARTICLE,#ID_RUBRIQUE}

met de functie:

formulaires_xxx_traiter_dist($arg1,$arg2){
...
}

zal $arg1 de waarde van #ID_ARTICLE en $arg2 die van #ID_RUBRIQUE krijgen.

Wat moet de functie doen

De functie traiter() voert alle benodigde handelingen uit naar aanleiding van de invoer door de internetter en doet dit na de verificatie door functie verifier().

Het belangrijke punt is dat de functie traiter() altijd moet worden opgeroepen na de functie verifier() en uitsluitend wanneer deze een lege fouttabel doorstuurt.

Wanneer de acties zijn uitgevoerd (bijvoorbeeld: het opslaan van de invoer, het versturen van een mail, enz.), moet de functie traiter() een tabel met waarden retourneren die het resultaat van de actie beschrijven.

Deze door traiter() verzonden tabel moet tenminste naar één van deze twee waardes verwijzen message_ok of message_erreur om de al dan niet succesvolle verwerking aan te geven.

message_ok
Is alles goed verlopen, dan krijgt de gebruiker hiervan de bevestiging. Het is een goed gebruik om altijd een bericht terug te sturen, ook als alles goed is verlopen!

message_erreur
Ondanks alle verificaties door de functie verifier() kan er toch iets misgaan. In dat geval geeft de functie traiter() een foutmelding via message_erreur en wordt de gebruiker ervan op de hoogte gebracht.

editable
Standaard wordt het invoerformulier niet opnieuw aangeboden, alleen het bericht van de al dan niet succesvolle verwerking.

Door een waarde true aan het veld editable te geven kan de gebruiker worden gevraagd het formulier opnieuw in te vullen.

id_xx
Heeft de verwerking één of meer gegevens in de database aangemaakt of aangepast, dan is het verstandig deze identificatiecodes, die normaal beginnen met id_, terug te sturen.

Zo kan een plugin die na de verwerking wil ingrijpen weten om welk object het gaat.

redirect
Een URL in dit veld geeft aan naar welke pagina de bezoeker moet worden doorgestuurd na de invoer van de gegevens.

Let op: het is belangrijk dat de functie traiter() zelf niet deze redirect bevat, omdat dit de interventie door een plugin na de functie traiter() zal verhinderen.

Voorbeeld van de functie traiter()
Een voorbeeld:

function formulaires_xxx_traiter_dist() {
	$res = array();
	$nom = _request('nom');
	$prenom = _request('prenom');
	$email = _request('email');
	
	include_spip('action/editer_auteur');
	if ($id_auteur = insert_auteur()) {
		auteurs_set($id_auteur,array('nom'=>"$nom $prenom",'email'=>$email));
		$res['message_ok'] = "Registratie geslaagd!";
		$res['id_auteur'] = $id_auteur;
	}
	else
		$res['message_erreur'] = "Er is een probleem opgetreden. De invoer kon niet worden verwerkt.";

	return $res;
}

Deze functie

• haalt de ingevoerde gegevens op;
• voegt de auteur toe aan de database tabel van auteurs in SPIP;
• registreert naam, voornaam en email voor deze auteur;
• geeft het resultaat van de toegevoegde id_auteur en een succesmelding.

Wanneer dit niet is gelukt, wordt een foutmelding terug gestuurd.

Bijzondere gevallen

Je kunt op formulieren eenvoudig de ajax functionaliteit toepassen door ze in een class ajax op te sluiten. De functies charger(), verifier() en traiter() weten dat niet en zien ook geen verschil.

Toch is het soms noodzakelijk dat de functie traiter() niet in ajax wordt opgeroepen. Bijvoorbeeld omdat zij een uitgebreide aanpassing van de database doet en vervolgens de gehele pagina opnieuw wordt getoond en niet alleen het formulier.

In dat geval moet je de functie traiter() laten beginnen met het aanroepen van de functie refuser_traiter_formulaire_ajax().

Is er geen sprake van ajax, dan doet deze functie niets en wordt de rest van de functie traiter() normaal uitgevoerd.

Is er wel sprake van ajax, dan stopr de functie en stuurt ze een specifieke code terug aan de JavaScript van de pagina. Wanneer de JavaScript deze code ontvangt, zorgt ze voor een hernieuwde verzending van de gegevens, maar zonder ajax. SPIP roept dus opnieuw de functie verifier() aan, gevolgd door de functie traiter(), die dit keer volledig zal worden uitgevoerd.

Het is dus essentieel dat de functie traiter() begint met het aanroepen van refuser_traiter_formulaire_ajax() en niet eerst andere handelingen verricht, die dan dubbel zullen worden uitgevoerd.

Personalisatie

Zoals bij charger() en verifier() kan de functie traiter() van een bestaand formulier via twee mechanismes worden gepersonaliseerd:

Surcharge
Zoals hierboven aangegeven, kan de standaardfunctie traiter() worden overschreven met een eigen functie function formulaires_xxx_traiter() die zal worden aangeroepen in plaats van de standaardfunctie, die de toevoeging _dist heeft.
Deze overschrijvende functie kan worden gedefinieerd in het bestand formulaires/xxx/traiter.php, of in een bestand options.php dat wordt aangeroepen bij elke hit.

Pipeline
De pipeline formulaire_traiter kan het resultaat van de standaardfunctie traiter() aanpassen, ongeacht het CVT-formulier.

Dit is de methode die de voorkeur heeft in een plugin.

De pipeline ontvangt als argument een tabel in deze vorm:

array(
	'args'=>array('form'=>$form,'args'=>$args),
	'data'=>$res)
)

Door de functie pipeline alsvolgt te schrijven

function mijnplugin_formulaire_traiter($flux){
...
}

Zul je in $flux de volgende elementen terugvinden:

Alle formulieren passeren dezelfde pipeline. Je moet dus de waarde van $flux['args']['form'] testen om te zorgen dat je uitsluitend het gedrag van formulier xxx beïnvloedt.

Lees ook functies charger() en verifier().