La funció charger() dels formularis CVT

Com definir la funció

La funció charger() d’un formulari XXX (que es mostrarà en els esquelets per #FORMULAIRE_XXX) està definida a dins del fitxer formulaires/xxx.php o a dins del fitxer formulaires/xxx/charger.php. La carpeta formulaires/ pot estar situada a dins de la carpeta d’un connector (plugin), o a dins de la carpeta squelettes.

Aquesta funció s’haurà d’anomenar function formulaires_xxx_charger_dist(). El sufix _dist permet a un desenvolupador tornar a definir la funció per tal de carregar el seu comportament, creant una funció function formulaires_xxx_charger()

Els arguments de la funció

La funció charger() rep automàticament, en el mateix ordre, el valor de cada argument passat a l’etiqueta #FORMULAIRE_XX. Per exemple escrivint

#FORMULAIRE_XX{#ID_ARTICLE, #ID_RUBRIQUE}

i la funció

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

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

Què ha de fer la funció

La funció charger() ha de tornar a enviar una taula de valors per defecte per cada camp d’introducció de dades del formulari. Aquesta taula té una funció doble:

• declarar la llista dels camps d’introducció de dades (la llista dels «name» dels input del formulari)
• proporcionar un valor per defecte per cada introducció de dades

Els valors per defecte proporcionats seran utilitzats a la primera publicació del formulari, però de seguida seran esborrats per les entrades de l’internauta en car de tornar-se a presentar el formulari degut a una introducció errònia.

Exemple de funció charger()
Vegem-ne un exemple

function formulaires_xxx_charger_dist() {
  $valeurs = array();
  $valeurs['nom'] = 'Indiquez votre nom';
  $valeurs['prenom'] = '';
  $valeurs['email'] = '';
  return $valeurs;
}

Aquí, la funció charger() reenviarà una taula associativa amb 3 camps ’cognom’, ’nom’, ’correu electrònic’ i un valor per defecte per a cada un d’ells.

Fins i tot si el valor per defecte està buit, és important que figuri el camp a la taula retornada per la funció charger(). En efecte, SPIP utilitza a continuació aquesta taula per saber quins camps s’han d’agafar.

No cal protegir el valor dels camps si contenen cometes, per exemple: SPIP ho farà automàticament.

Cada valor del camp serà retrobat a dins de l’esquelet del formulari html amb, per exemple aquí, #ENV{cognom}, #ENV{nom}, #ENV{correu electrònic}

Camps especials

La funció charger() pot reenviar alguns valors especials.

editable
Aquest valor s’utilitza a dins de l’esquelet del formulari per permetre o no la introducció de dades. Per defecte, després del tractament del formulari, «editable» és fals i la introducció de dades del formulari no es torna a proposar. Només ex mostrarà el missatge d’èxit.

És possible proporcionar aquí un valor per «editable» per tal de gestionar condicions especials sobre l’activació o no de la introducció de dades del formulari.

message_ok
El missatge d’èxit és proporcionat, en principi, per la funció traiter(). De tota manera també és possible proporcionar-la per la funció charger() de manera derogatòria.

message_erreur
El missatge d’error està proporcionat, en principi, per la funció traiter(). No obstant també és possible proporcionar-lo per la funció charger() de manera derogatòria

action
Aquest valor precisa el URL on s’ubica el formulari. Per defecte és el URL de la pàgina en curs. És important que aquesta sigui la norma general ja que, en cas d’error d’entrada, cal poder tornar a presentar el formulari.

En certs casos derogatoris, pot ser útil modificar aquest URL. Reservar-ho per usos molt especials.

_forcer_request
Per defecte, SPIP verifica que el formulari enviat sigui el bo per permetre tenir diversos formularis del mateix tipus en una pàgina, i només tractar aquells que ha estat sotmès. La verificació està basada sobre la llista d’arguments passats a l’etiqueta #FORMULAIRE_XXX.

En alguns casos, quan aquests arguments canvien degut a l’entrada de dades, SPIP es pot equivocar i creure que l’entrada prové d’un altre formulari.
Passant-li true pour _forcer_request, li indiqueu que no ha de fer aquesta verificació i que ha de tractar l’entrada de dades en tots els casos.

_action
Si el tractament del formulari xxx ha de cridar una funció del directori actions/ que està protegit per securiser_action(), és possible, indicant el nom de l’acció, que SPIP proporcioni automàticament el hash de protecció corresponent.

_hidden
El valor d’aquest camps s’afegirà directament al codi HTML del formulari generat. S’utilitza per afegir els input hidden que haurien de ser escrits explícitament:

$valeurs['_hidden'] = "<input type='hidden' name='secret' value='hop' />";

_pipeline
Aquest camp permet demanar a aquest que el resultat del càlcul del formulari passi a dins del pipeline esmentat, permetent la seva extensió pels connectors.
Això pot ser una simple cadena, per definiri el nom del pipeline:

$valeurs['_pipeline'] = "monpipeline";

on una taula de dos valors, per precisar arguments a passar al pipeline:

$valeurs['_pipeline'] = array("monpipeline", array('arg1' => 'unevaleur', ...));

Pre-fixació i la protecció camps per a l’ingrés de dades
Per defecte, tots els valors de la taula estan protegits per tal de poder ser inserits en total seguretat a dins de l’atribut value d’un input a dins de l’esquelet del formulari. Quan el valor és en sí mateix una taula, cadascun dels seus valors età protegit i així successivament.

No obstant, els camps prefixats per un _ (underscore) no seran automàticament protegits per SPIP. Quan sigui necessari passar valors a l’esquelet, però que no s’utilitzaran per l’entrada de dades, és aconsellable utilitzar sistemàticament aquest prefix.

Per altra banda, no cal utilitzar un prefix _ (underscore) per un camp d’entrada de dades, ja que el valor entrat per l’usuari s’ignora quan el formulari es torna a presentar en cas d’error.

Personalització

Una funció charger() d’un formulari existent es pot personalitzar mitjançant dos mecanismes:

Sobrecàrrega
Tal i com s’indica més avall, és possible tornar a definir la funció charger() per defecte definint la seva pròpia funció function formulaires_xxx_charger() que serà cridada en la lloc de la funció per defecte que comporta el sufix _dist. Aquesta sobrecàrrega es podrà situar a dins del fitxer formulaires/xxx/charger.php, o a dins d’un fitxer options.php sempre carregat.

Pipeline
El pipeline formulaire_charger permet modificar el resultat de la funció charger() per defecte de qualsevol formulari CVT.

És el mètode que cal privilegiar en un connector (plugin).

El pipeline rep en argument una taula d’aquesta manera:

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

Escrivint la funció pipeline d’aquesta forma

function monplugin_formulaire_charger($flux){
...
}

el seu argument comportarà els següents elements:

Tots els formularis passen pel mateix pipeline. Cal, per tant, provar el valor de $flux['args']['form'] per només modificar el comportament del formulari al respecte.

Vegeu també les funcions verificar() i tractar()