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/ peut être dans le dossier d’un plugin, ou dans le dossier squelettes.
Elle devra être nommée
function formulaires_xxx_charger_dist(). Le suffixe _dist permet à un développeur 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 la valeur de chaque argument qui sont passés à la balise #FORMULAIRE_XX, dans le même ordre. Par exemple en écrivant
et la fonction
$arg1 recevra #ID_ARTICLE, et $arg2 recevra #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
Ici, la fonction charger va renvoyer un tableau associatif avec 3 champs ’nom’, ’prenom’, ’email’, et une valeur par défaut pour chaque.
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. Seuls 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 en principe fournit 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 en principe fournit 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érogatoire, il peut être utile de modifier cette url. A 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 où 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 veirifcation et 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 champs sera ajoutée directement dans le html du formulaire généré. Elle est utilisée pour y ajouter des input hidden qui devront être écrits explicitements :
Préfixage Les champs préfixés par un _ ne seront pas protégés automatiquement par SPIP. Il peut être utile de préfixer certains noms de champs dont la valeur est complexe pour les passer tels quels au squelette en formulaire.
Personnalisation
Une fonction charger d’un formulaire existant peut être personalisée par deux mécanismes
Surcharge
Comme indiqué ci-dessus, il est possible de re-definir 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 un suffixe _dist.
Cette fonction surchargée pourra être définie dans le fichier formulaires/xxx/charger.php, ou dans un fichier options.php appelé à chaque hit de façon à ce que la fonction soit défini au moment où SPIP va la chercher.
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 :
En ecrivant la fonction pipeline sous cette forme
Alors vous trouverez dans $flux les éléments suivants :
$flux['args']['form'] |
nom du formulaire (xxx dans notre exemple) |
$flux['args']['args'] |
arguments de la fonction charger dans l’ordre où ils ont été passés à la balise #FORMULAIRE_XXX |
$flux['args']['data'] |
tableau $valeurs renvoyé par la fonction charger() par défaut |
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.