La fonction verifier() des formulaires CVT

Comment définir la fonction

La fonction verifier() 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/verifier.php. Le dossier formulaires/ pouvant être rangé dans le dossier d’un plugin, ou dans le dossier squelettes.

Cette fonction devra être nommée
function formulaires_xxx_verifier_dist(). Le suffixe _dist permettant lors du développement de surcharger la fonction pour changer son comportement, en créant une fonction function formulaires_xxx_verifier()

Les arguments de la fonction

La fonction verifier() reçoit automatiquement la valeur de chaque argument qui sont passés à la balise #FORMULAIRE_XX, dans le même ordre.
Par exemple en écrivant

#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}

et la fonction

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

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

Que doit faire la fonction

La fonction verifier() doit renvoyer un tableau d’erreurs de saisies résultant de la vérification des données saisies.

Si toute la saisie est correcte, le tableau sera vide, et SPIP appellera alors la fonction traiter() du formulaire, chargée de finir le travail.

Si le tableau renvoyé par la fonction verifier() n’est pas vide, alors la fonction traiter() ne sera pas appelée, le formulaire sera de nouveau affiché avec les messages d’erreur éventuels pour correction par l’utilisateur.

Il convient donc de faire toutes les vérifications nécessaires au traitement dans la fonction verifier() pour assurer la meilleure interactivité possible.

Chaque erreur est renvoyée sous forme d’une association cle=>valeur, et il est d’usage d’utiliser comme clé le nom de la variable saisie dans le formulaire.

Exemple de fonction verifier()
Voyons un exemple

function formulaires_xxx_verifier_dist() {
	$erreurs = array();
	if (!_request('nom')) {
		$erreurs['nom'] = _T('info_obligatoire');
	}
	include_spip('inc/filtres');
	if ($email = _request('email')  AND !email_valide($email)) {
		$erreurs['email'] = _T('form_email_non_valide');
	}
	return $erreurs;
}

Ici, la fonction

• vérifie que le nom a bien été renseigné, et produit un message d’erreur dans le cas contraire ;
• regarde si une adresse mail a été saisie, et dans ce cas vérifie sa validité, avec un message d’erreur si l’adresse mail est incorrecte.

Champs particuliers

La fonction verifier() peut renvoyer certaines valeurs particulières dans le tableau :

message_erreur
Cette valeur est utilisée dans le squelette du formulaire pour afficher un message d’erreur général, qui concerne tout le formulaire. Il peut être judicieux de renseigner ce message dès qu’une erreur sur un champ a été identifiée

message_ok
Cette valeur permet de renvoyer un message de succès. Ce message peut-être utile quand par exemple l’internaute a entré une première valeur qui permet de vérifier certaines informations, sans que la saisie du formulaire ne soit finie pour autant.
La présence de ce message empêche l’appel à la fonction traiter() du formulaire, qui n’est appelée que si, et seulement si, le tableau retourné par verifier() est vide.

Personnalisation

Comme la fonction charger(), la fonction verifier() 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 verifier() par défaut en définissant sa propre fonction
function formulaires_xxx_verifier()
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/verifier.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_verifier permet de modifier le résultat de la fonction verifier() 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'=>$erreurs
)

En écrivant la fonction pipeline sous cette forme

function monplugin_formulaire_verifier($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() et traiter()