Com definir la funció
La funció verifier() d’un formulari XXX (que es mostrarà en els esquelets per #FORMULAIRE_XXX) està definida en el fitxer formulaires/xxx.php o en el fitxer formulaires/xxx/verifier.php. La carpeta formulaires/ es pot guardar a dins de la carpeta d’un plugin, o a dins de la carpeta squelettes.
Aquesta funció s’haurà d’anomenar
function formulaires_xxx_verifier_dist(). El sufix _dist permet a un desenvolupador sobrecarregar la funció per canviar el seu comportament, creant una funció function formulaires_xxx_verifier()
Els arguments de la funció
La funció verifier() rep automàticament el valor de cada argument i aquests es passen a l’etiqueta #FORMULAIRE_XX, en el mateix ordre. Per exemple escrivint
#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}
i la funció
formulaires_xxx_verifier_dist($arg1,$arg2){
...
}
$arg1 valdrà #ID_ARTICLE, i $arg2 valdrà #ID_RUBRIQUE.
Que ha de fer la funció
La funció verifier() ha de reenviar una taula d’error de les entrades com a resultat de la verificació de les dades introduïdes.
Si totes les entrades són correctes, la taula estarà buida, i SPIP cridarà llavors la funció traiter() del formulari, encarregada d’acabar el treball.
Si la taula reenviada per la funció verifier() no està buida, llavors no es cridarà la funció traiter() i el formulari es mostrarà de nou amb els missatges d’error eventuals per tal que siguin corregits per l’usuari.
Per tant, convé fer totes les verificacions necessàries al tractament a dins de la funció verifier() per assegurar-nos la millor interactivitat possible.
Cada error és reenviat en forma d’una associació cle=>valeur, i és costum de fer servir com a clau el nom de la variable introduïda en el formulari.
Exemple de la funció verifier()
Vegem 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;
}
Aquí, la funció
- verifica que el nom hagi estat ben informat, i produeix un missatge d’error en cas contrari;
- mira si s’ha introduït una adreça de correu electrònic, i en aquest cas verifica la seva validesa, amb un missatge d’error si l’adreça de correu electrònic és incorrecta.
Camps particulars
La funció verifier() pot reenviar alguns valors particulars a dins la taula:
message_erreur
Aquest valor s’utilitza en l’esquelet del formulari per mostrar un missatge d’error general, que afecta a tot el formulari. Pot ser intel·ligent de mostrar aquest missatge des del mateix moment que s’identifica un error en un camp.
message_ok
Aquest valor permet reenviar un missatge d’èxit. Aquest missatge pot ser útil quan, per exemple, l’internauta ha entrat un primer valor que permet verificar certes informacions, i per tant sense que l’entrada de dades del formulari s’hagi acabat.
La presència d’aquest missatge impedeix la crida a la funció traiter() del formulari, que només es crida si la taula retornada per verifier() està buida.
Personalització
Com la funció charger(), la funció verifier() d’un formulari existent pot se personalitzada per dos mecanismes
Surcharge
Tal i com s’indica més amunt, és possible redefinir la funció verifier() per defecte tot definint la seva pròpia funció
function formulaires_xxx_verifier()
que serà cridada en lloc de la funció per defecte que comporta el sufix _dist.
Aquesta funció sobrecarregada es podrà definir en el fitxer formulaires/xxx/verifier.php, o en el fitxer options.php cridat a cada hit de manera que la funció es defineixi en el moment quan SPIP la va a buscar.
Pipeline
El pipeline formulaire_verifier permet modificar el resultat de la funció verifier() per defecte de qualsevol formulari CVT.
És el mètode que cal afavorir en un plugin.
Le pipeline rep en argument una taula que tindrà aquesta forma:
array(
'args'=>array('form'=>$form,'args'=>$args),
'data'=>$erreurs)
)
Escrivint la funció pipeline d’aquesta manera
funció monplugin_formulaire_verifier($flux){
...
}
Llavors, trobareu a $flux els següents elements:
$flux['args']['form'] |
nom del formulari (xxx en el nostre exemple) |
$flux['args']['args'] |
arguments de la funció charger() en l’ordre en el que han estat passats a l’etiqueta #FORMULAIRE_XXX |
$flux['args']['data'] |
taula $erreurs reenviada per la funció verifier() per defecte |
Tots els formularis passen pel mateix pipeline. Per tant, s’ha de provar el valor de $flux['args']['form'] per modificar només el comportament del formulari xxx.