La fonction charger() des formulaires CVT

Comment définir la fonction

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

Cette fonction devra être nommée
function formulaires_xxx_charger_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_charger()

Les arguments de la fonction

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

#FORMULAIRE_XX{#ID_ARTICLE, #ID_RUBRIQUE}

et la fonction

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

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

Que doit faire la fonction

La fonction charger() doit renvoyer un tableau de valeurs par défaut pour chaque champ de saisie du formulaire.
Ce tableau a une double fonction :

• déclarer la liste des champs saisis (la liste des « name » des input du formulaire)
• fournir une valeur par défaut pour chaque saisie

Les valeurs par défaut fournies seront utilisées au premier affichage du formulaire, mais seront ensuite écrasées par les saisies de l’internaute en cas de re-présentation du formulaire suite à une erreur de saisie.

Exemple de fonction charger()
Voyons un exemple

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

Ici, la fonction charger() va renvoyer un tableau associatif avec 3 champs ’nom’, ’prenom’, ’email’ et une valeur par défaut pour chacun d’entre-eux.

Même si la valeur par défaut est vide, il est important de faire figurer le champ dans le tableau retourné par la fonction charger(). En effet, SPIP utilise ensuite ce tableau pour savoir quels champs seront saisis.

Il n’est pas nécessaire de protéger la valeur des champs si ils contiennent des guillemets par exemple : SPIP le fera automatiquement.

Chaque valeur du champ sera retrouvée dans le squelette du formulaire html avec, par exemple ici, #ENV{nom}, #ENV{prenom}, #ENV{email}

Champs particuliers

La fonction charger() peut renvoyer certaines valeurs particulières

editable
Cette valeur est utilisée dans le squelette du formulaire pour permettre ou non la saisie. Par défaut, après le traitement du formulaire, « editable » est faux et la saisie du formulaire n’est pas re-proposée. Seul le message de succès est affiché.

Il est possible de fournir ici une valeur pour « editable » pour gérer des conditions particulières sur l’activation ou non de la saisie du formulaire.

message_ok
Le message de succès est fourni, en principe, par la fonction traiter(). Il est néanmoins possible de le fournir par la fonction charger() de manière dérogatoire.

message_erreur
Le message d’erreur est fourni, en principe, par la fonction traiter(). Il est néanmoins possible de le fournir par la fonction charger() de manière dérogatoire.

action
Cette valeur précise l’URL sur laquelle est postée le formulaire. C’est par défaut l’URL de la page en cours. Il est important que cela reste le cas général car en cas d’erreur de saisie, il faut pouvoir re-présenter le formulaire.

Dans certains cas dérogatoires, il peut être utile de modifier cette URL. À réserver à des usages très particuliers.

_forcer_request
Par défaut, SPIP vérifie que le formulaire posté est bien le bon pour permettre d’avoir plusieurs formulaires du même type dans une page, et ne traiter que celui qui a été soumis. La vérification est basée sur la liste des arguments passés à la balise #FORMULAIRE_XXX.

Dans certains cas, quand ces arguments changent suite à la saisie, SPIP peut se tromper et croire que la saisie vient d’un autre formulaire.
En lui passant true pour _forcer_request, vous lui indiquez qu’il ne doit pas faire cette vérification et qu’il doit traiter la saisie dans tous les cas.

_action
Si le traitement du formulaire xxx doit faire appel à une fonction du répertoire actions/ qui est protégée par securiser_action(), il est possible, en indiquant le nom de l’action, que SPIP fournisse automatiquement le hash de protection correspondant.

_hidden
La valeur de ce champ sera ajoutée directement dans le code HTML du formulaire généré. Elle est utilisée pour y ajouter des input hidden qui devront être écrits explicitement :

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

_pipeline
Ce champ permet de demander à ce que le résultat du calcul du formulaire passe dans le pipeline mentionné, permettant son extension par des plugins.
Ce peut être une simple chaîne, pour définir le nom du pipeline :

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

ou un tableau de deux valeurs, pour préciser des arguments à passer au pipeline :

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

Pré-fixage et protection des champs pour saisie
Par défaut, toutes les valeurs du tableau sont protégées pour pouvoir être insérées en toute sécurité dans l’attribut value d’un input dans le squelette du formulaire. Lorsque la valeur est elle-même un tableau, chacune de ses valeurs est protégée et ainsi de suite.

Toutefois, les champs préfixés par un _ (underscore) ne seront pas protégés automatiquement par SPIP. Lorsqu’il est nécessaire de passer des valeurs au squelette, mais qui ne seront pas utilisées pour la saisie, il est conseillé d’utiliser systématiquement ce préfixe.

Par ailleurs, il ne faut pas utiliser un préfixe _ (underscore) pour un champ de saisie, car la valeur entrée par l’utilisateur est ignorée lorsque le formulaire est re-présenté en cas d’erreur.

Personnalisation

Une fonction charger() 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 charger() par défaut en définissant sa propre fonction
function formulaires_xxx_charger()
qui sera appelée à la place de la fonction par défaut qui comporte le suffixe _dist.
Cette surcharge pourra être placée dans le fichier formulaires/xxx/charger.php, ou dans un fichier options.php toujours chargé.

Pipeline
Le pipeline formulaire_charger permet de modifier le résultat de la fonction charger() 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' => $valeurs)
)

En écrivant la fonction pipeline sous cette forme

function monplugin_formulaire_charger($flux) {
...
}

son argument comportera 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 concerné.

Voir aussi les fonctions verifier() et traiter()