La fonction traiter() des formulaires CVT

Comment définir la fonction

La fonction traiter() d’un formulaire XXX (qui sera affiché dans les squelettes par #FORMULAIRE_XXX) est définie dans le fichier formulaires/xxx.php ou dans le fichier formulaires/xxx/traiter.php. Le dossier formulaires/ pouvant être placé dans le dossier d’un plugin, ou dans le dossier squelettes.

La fonction devra être nommée
function formulaires_xxx_traiter_dist(). Le suffixe _dist permettant lors du développement de redéfinir la fonction pour changer son comportement, en créant une fonction function formulaires_xxx_traiter()

Les arguments de la fonction

Comme les fonctions charger() et verifier(), la fonction traiter() reçoit automatiquement, dans le même ordre, la valeur de chacun des arguments passés à la balise #FORMULAIRE_XX.
Par exemple en écrivant

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

et la fonction

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

$arg1 vaudra #ID_ARTICLE, et $arg2 vaudra #ID_RUBRIQUE.

Que doit faire la fonction

La fonction traiter() fait tous les traitements nécessaires suite à la saisie de l’internaute, et après les vérifications faites par la fonction verifier().

Le point important ici est que la fonction traiter() sera toujours appelée juste après la fonction verifier() et uniquement si celle-ci a bien renvoyé un tableau vide signifiant l’absence d’erreurs.

Une fois les actions réalisées (par exemple : enregistrement des données, écriture dans un fichier, envoi de mail ...), la fonction traiter() doit renvoyer un tableau de valeurs décrivant le résultat de l’action.

Ce tableau renvoyé par traiter() doit renseigner au moins une des deux valeurs message_ok ou message_erreur pour indiquer le succès ou l’échec éventuel du traitement.

message_ok
Si tout c’est bien déroulé, l’indiquer dans un message permet à l’utilisateur d’être rassuré sur l’action réalisée. C’est une bonne pratique de toujours renvoyer un message, même si tout se passe bien !

message_erreur
Malgré les vérifications réalisées par la fonction verifier(), le traitement peut échouer pour d’autres raisons non détectables à l’avance. Dans ce cas la fonction traiter() indique la cause de l’erreur dans message_erreur, et l’utilisateur sera informé du problème.

editable
Par défaut, après la saisie du formulaire et son traitement avec succès, la saisie du formulaire ne sera pas re-proposée, seul le message de succès ou d’erreur étant affiché.

En renvoyant une valeur true pour ce champ, cela permet de demander à l’utilisateur de remplir à nouveau le formulaire.

id_xx
Si le traitement a inséré ou modifié une (ou plusieurs) donnée en base, il est judicieux de renvoyer les clé primaires, généralement commençant par id_, des enregistrements concernés.

Ainsi, un plugin qui veut intervenir à la suite du traitement par défaut sait sur quel objet a porté l’opération, et peut agir en complément.

redirect
Il suffit d’indiquer une url dans ce champ pour rediriger l’internaute sur une autre page après la saisie.

Attention, il est important que la fonction traiter() ne fasse pas elle-même la redirection, car cela empêcherait tout intervention d’un plugin à la suite de la fonction traiter().

Exemple de fonction traiter()

Voyons un exemple

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'] = "Enregistrement réussi !";
		$res['id_auteur'] = $id_auteur;
	}
	else {
		$res['message_erreur'] = "Un probleme a été rencontré, impossible d'enregistrer votre saisie";
	}
	return $res;
}

Ici, la fonction

• récupère les informations saisies ;
• ajoute un auteur dans la table des auteurs de SPIP ;
• enregistre les nom, prénom et email saisis pour cet auteur ;
• indique dans le résultat l’id_auteur ajouté, ainsi que le message de succès.

Si l’auteur ne peut être ajouté, un message d’erreur est renvoyé.

Cas particuliers

Les formulaires peuvent être facilement ajaxés en les incluant dans une classe ajax. Les fonctions charger(), verifier() et traiter() n’en savent rien, et ne voient pas de différence.

Cependant, il est parfois nécessaire que la fonction traiter() ne soit pas appelée en ajax. Par exemple parcequ’elle va modifier fortement la base de données et qu’il est préférable que toute la page soit ré-affichée après la saisie, pas seulement le formulaire.

Dans ce cas, il faut commencer la fonction traiter() par un appel à la fonction
refuser_traiter_formulaire_ajax().

Si le formulaire n’a pas été soumis en ajax, cette fonction ne fera rien, et la suite de la fonction traiter() sera exécutée normalement.

Si le formulaire a été soumis en ajax, alors cette fonction va tout arrêter en renvoyant un code spécifique au javascript de la page. Lorsque le javascript reçoit ce code, il provoque à nouveau un envoi des données du formulaire, mais sans ajax cette fois-ci. SPIP va alors de nouveau appeler la fonction verifier(), puis la fonction traiter(), qui cette fois s’exécutera complètement et pourra réaliser ses opérations.

Il est donc primordial que la fonction traiter() commence par cet appel à refuser_traiter_formulaire_ajax(), et ne fasse aucune manipulation avant d’appeler cette fonction, car sinon ces éventuelles opérations seraient exécutées deux fois.

Personnalisation

Comme les fonctions charger() et verifier(), la fonction traiter() d’un formulaire existant peut être personnalisée par deux mécanismes

Surcharge
Comme indiqué ci-dessus, il est possible de redéfinir la fonction traiter() par défaut en définissant sa propre fonction
function formulaires_xxx_traiter()
qui sera appelée à la place de la fonction par défaut qui comporte le suffixe _dist.
Cette fonction surchargée pourra être définie dans le fichier formulaires/xxx/traiter.php, ou dans un fichier options.php appelé à chaque hit de façon à ce que la fonction soit définie au moment où SPIP va la chercher.

Pipeline
Le pipeline formulaire_traiter permet de modifier le résultat de la fonction traiter() par défaut de n’importe quel formulaire CVT.

C’est la méthode qu’il faut privilégier dans un plugin.

Le pipeline reçoit en argument un tableau de cette forme :

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

En écrivant la fonction pipeline sous cette forme

function monplugin_formulaire_traiter($flux) {
	...
}

Alors vous trouverez dans $flux les éléments suivants :

Tous les formulaires passent par le même pipeline. Il faut donc tester la valeur de $flux['args']['form'] pour ne modifier que le comportement du formulaire xxx.

Voir aussi

Les fonctions

• charger()
• verifier()

Sur programmer.spip.net

• le pipeline formulaire_traiter
• les formulaires CVT
• d’autres exemples