Com definir la funció
La funció traiter() d’un formulari XXX (que es mostrarà als esquelets per #FORMULAIRE_XXX) es defineix en el fitxer formulaires/xxx.php o en el fitxer formulaires/xxx/traiter.php. La carpeta formulaires/ es pot posar a dins de la carpeta d’un plugin, o a dins de la carpeta squelettes.
La funció s’haurà d’anomenar function formulaires_xxx_traiter_dist(). El sufix _dist permetrà a un desenvolupador tornar a definir la funció per canviar el seu comportament, creant una funció function formulaires_xxx_traiter()
Els arguments de la funció
Com les funcions charger() i verifier(), la funció traiter() rep automàticament, en el mateix ordre, el valor de cadascun dels arguments passats a l’etiqueta #FORMULAIRE_XX. Escrivint, per exemple
#FORMULAIRE_XX{#ID_ARTICLE,#ID_RUBRIQUE}
i la funció
formulaires_xxx_traiter_dist($arg1,$arg2){
...
}
$arg1 vaudra #ID_ARTICLE, et $arg2 vaudra #ID_RUBRIQUE.
Què ha de fer la funció
La funció traiter() fa tots els tractaments necessaris com a conseqüència de l’entrada de dades de l’internauta, i després de les verificacions fetes per la funció verifier().
El punt important aquí és que la funció traiter() es cridarà sempre just després de la funció verifier() i només si aquesta ha enviat correctament una taula buida que significa l’absència d’errors.
Un cop realitzades les accions (per exemple: enregistrament de dades, escriptura en un fitxer, enviament d’un correu electrònic...), la funció traiter() ha de retornar una taula de valors que descrigui el resultat de l’acció.
Aquesta taula retornada per traiter() ha d’informar com a mínim d’un dels dos valors message_ok o message_erreur per indicar l’èxit o el fracàs eventual del tractament.
message_ok
Si tot s’ha desenvolupat correctament, l’indicador a dins d’un missatge permet a l’usuari quedar tranquil respecte a l’acció realitzada. És una bona pràctica tornar a enviar sempre un missatge, fins i tot quan tot ha anat bé!
message_erreur
Malgrat les verificacions realitzades per la funció verifier(), el tractament pot fracasar per altres raons no detectables prèviament. En aquest cas, la funció traiter() indica la causa de l’error a dins de message_erreur, i l’usuari serà informat del problema.
editable
Per defecte, després de la introducció de dades al formulari i del seu tractament amb èxit, la possibilitat d’omplir dades al formulari no es tornarà a proposar, mostrant-se únicament el missatge d’èxit o d’error.
Si donem un valor true a aquest camp, podrem aconseguir que l’usuari pugui omplir altre cop el formulari.
id_xx
Si el tractament ha inserit o modificat una (o diverses) dades de la base, és assenyat tornar a enviar les claus primàries, que comencen generalment per id_, dels enregistraments afectats.
D’aquesta manera, un plugin que vulgui intervenir a continuació del tractament sap, per defecte, sobre quin objecte s’ha dirigit la operació, i pot actuar com a complement.
redirect
N’hi ha prou indicant un url en aquest camp per redirigir a l’internauta cap a una altra pàgina després de la introducció de dades.
Alerta, és important que no sigui la funció traiter(), pròpiament dita, qui faci la redirecció ja que això impediria qualsevol intervenció d’un plugin a continuació de la funció traiter().
Exemple de funció traiter()
Vegem un exemple
function formulaires_xxx_traiter_dist() {
$res = array();
$nom = _request('cognom');
$prenom = _request('nom');
$email = _request('correu electrònic');
include_spip('action/editer_auteur');
if ($id_auteur = insert_auteur()) {
auteurs_set($id_auteur,array('nom'=>"$nom $prenom",'email'=>$email));
$res['message_ok'] = "Enregistrament amb èxit!";
$res['id_auteur'] = $id_auteur;
}
else
$res['message_erreur'] = "S'ha trobat un problema i no es poden registrar les dades introduïdes";
return $res;
}
Aquí, la funció
- recupera les informacions introduïdes;
- afegeix un autor a la taula dels autors d’SPIP ;
- enregistra el cognom, nom i correu electrònic d’aquest autor;
- indica en el resultat l’id_auteur afegida, així com el missatge d’èxit.
Si l’autor no es pot afegir, s’envia un missatge d’error.
Casos particulars
Als formularis se’ls pot afegir Ajax fàcilment si els incloem en una classe ajax. Les funcions charger(), verifier() i traiter() no ho sabran i no hi veuran cap diferència.
No obstant, a vegades es necessari que la funció traiter() no sigui cridada en ajax. Per exemple, si se sap que aquesta modificarà fortament la base de dades i que és preferible que tota la pàgina es mostri de nou altre cop un cop introduïdes les dades i no només el formulari.
En aquest cas, cal començar la funció traiter() mitjançant una crida a la funció
refuser_traiter_formulaire_ajax().
Si el formulari no s’ha sotmès en ajax, aquesta funció no farà res i la continuació de la funció traiter() s’executarà normalment.
En canvi, si el formulari ha estat sotmès en ajax, aquesta funció es pararà enviant un codi específic al javascript de la pàgina. Quan el javascript rep aquest codi, provoca un nou enviament de dades del formulari, però aquesta vegada sense ajax. Llavors, SPIP cridarà altre cop la funció verifier(), després la funció traiter(), que aquest cop s’executarà completament i podrà realitzar les seves operacions.
Per tant, és primordial que la funció traiter() comenci per aquesta crida a refuser_traiter_formulaire_ajax(), i no faci cap manipulació abans de cridar aquesta funció, ja que sinó aquestes eventuals operacions s’executarien dues vegades.
Personalització
De la mateixa manera que les funcions charger() i verifier(), la funció traiter() d’un formulari existent es pot personalitzar mitjançant dos mecanismes
Recarregar
Tal i com s’indica més amunt, és possible tornar a definir la funció traiter() per defecte tot definint la seva pròpia funció
function formulaires_xxx_traiter()
que serà cridada en lloc de la funció per defecte que porta el sufix _dist.
Aquesta funció recarregada es podrà definir a dins del fitxer formulaires/xxx/traiter.php, o a dins d’un fitxer options.php cridat a cada hit de tal manera que la funció es defineixi al mateix moment que SPIP la va a buscar.
Pipeline
El pipeline formulaire_traiter permet modificar el resultat de la funció traiter() per defecte de qualsevol formulari CVT.
És el mètode el què cal privilegiar en un plugin.
El pipeline rep en argument una taula d’aquesta manera:
array(
'args'=>array('form'=>$form,'args'=>$args),
'data'=>$res)
)
Escrivint la funció pipeline d’aquesta manera
function monplugin_formulaire_traiter($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 que són passats a l’etiqueta #FORMULAIRE_XXX |
$flux['args']['data'] |
taula $res reenviada per la funció traiter() per defecte |
Tots els formularis passen pel mateix pipeline. Cal, per tant, provar el valor de $flux['args']['form'] per modificar només el comportament del formulari xxx.
vegeu, també, les funcions charger() i verifier()