API CFG : #FORMULAIRE_XX

SPIP et les formulaires publics

Une nouvelle API pour réaliser des formulaires publics a été introduit dans la version de SPIP 2.0 en développement. Réaliser un formulaire public nécessite maintenant 2 fichiers :
-  formulaires/x.html contient le formulaire
-  formulaires/x.php contient 3 fonctions :

• formulaires_x_charger() charge les valeurs par défaut
• formulaires_x_verifier() vérifie les valeurs envoyées lors de l’envoi du formulaire
• formulaires_x_traiter() effectue des traitements si les valeurs envoyées sont valides.

Ces formulaires peuvent être rechargés en ajax, c’est à dire que seul la partie contenant le formulaire est actualisée, et non toute la page. Pour utiliser l’ajax, il faut encadrer le formulaire par une classe css ajax, par exemple en l’intégrant dans une balise <div class="ajax">

Fonctionnement des formulaires CVT avec CFG

Lorsqu’un formulaire dynamique placé dans le dossier formulaires/ n’a pas de fonction charger() alors c’est le parseur et les fonctions charger, vérifier et traiter de CFG qui sont utilisées.

Pour appeler un formulaire, il suffit d’indiquer son nom :
-  #FORMULAIRE_X

Il est possible de passer un identifiant (cfg_id) en premier paramètre du formulaire (rarement nécessaire)
-  #FORMULAIRE_X{#ID_ARTICLE}

Adapter le fond CFG

Pour permettre à votre formulaire CFG d’être lu de la sorte, il faut qu’il contienne la balise #ACTION_FORMULAIRE{#SELF} et que le champ action du formulaire soit rempli. Cela donne :

<form method="post" action="#SELF"><div>
#ACTION_FORMULAIRE{#SELF}
...
</div></form>

Attention :
-  [(#ENV{_cfg_}|form_hidden)] n’est plus nécessaire.

Afficher les messages de réussite ou d’echec

l’API des formulaires SPIP retourne plusieurs types de messages qui sont transmis à l’environnement : message_ok, message_erreur ainsi qu’un tableau erreurs qui contient des informations d’erreur pour chaque champ.

Ils s’utilisent comme ceci :

[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
[<p class="formulaire_message">(#ENV*{message_ok})</p>]

[<span class='erreur'>(#ENV**{erreurs}|table_valeur{email_webmaster})</span>]

Formulaire minimal

Soit le formulaire formulaires/z.html contenant :

<!-- titre=Exemple sur le champ 'description' du site -->
<!-- depot=meta -->

#CACHE{0}

[<p class='formulaire_erreur'>(#ENV*{message_erreur})</p>]
[<p class="formulaire_message">(#ENV*{message_ok})</p>]

<form method="post" action="#SELF"><div>
#ACTION_FORMULAIRE{#SELF}

<label>Description du site</label>
<textarea name="description" rows="4" cols="40">[(#ENV{description})]</textarea>
[<span class='erreur'>(#ENV**{erreurs}|table_valeur{description})</span>]

<input type="submit" name="_cfg_ok" value="<:cfg:OK:>" />
</div></form>

Il peut être appelé par #FORMULAIRE_Z.

Le champ description sera enregistré, par défaut, dans z/description (que l’on peut récupérer donc par #CONFIG{z/description}. Pour enregistrer ailleurs, vous pouvez utiliser tous les paramètres CFG à votre disposition. Par exemple en mettant : <!-- nom=ici -->, cela enregistrera la valeur dans ici/description

Intégrer ces formulaires dans les pages ?exec=cfg&cfg=xx

Par défaut, ces formulaires ne s’ajoutent pas aux menus de la page ?exec=cfg, ni ne peuvent être appelés directement avec ?exec=cfg&cfg=xx si le formulaire est nommé #FORMULAIRE_XX.

Pour ajouter ce type de formulaire, il faut créer un autre fond différent du nom du formulaire (donc pas fonds/cfg_xx.html). Ce fond pourra recevoir des paramètres de CFG concernant l’affichage de la page (paramètres onglet, liens). Ce fond devra posséder le paramètre <!-- interpreter=non --> qui indique à CFG qu’il ne doit pas rechercher (analyser la page html retournée) des champs de formulaire dans cette page.

Si ce paramètre n’est pas présent, CFG va considérer les paramètres inclus par les #FORMULAIRE comme des champs à récupérer, ce qui pourrait entrainer des erreurs imprévues (exemple : lire une colonne qui n’existe pas dans une table provoquant une erreur sql).

Pour ces raisons, il est conseillé fortement, dans ce genre de fonds appelant des #FORMULAIRE de ne pas mettre en plus un formulaire CFG classique (<form>...</form>). Par contre, il est tout à fait possible de mettre plusieurs #FORMULAIRE différents.

Exemple de fond/cfg_plugin.html :

<!-- interpreter=non -->
<!-- description=Description de la page -->

<div class='ajax'>
#FORMULAIRE_XX
</div>

<!-- il est possible de mettre plusieurs formulaires dans un même fond -->
<div class="ajax">
#FORMULAIRE_YY
</div>