Introduction

Les formulaires de SPIP 2.0 sont maintenant découpés en 4 parties :

• le HTML qui gère l’affichage graphique du formulaire,
• la fonction charger() insère les valeurs préremplies,
• la fonction verifier() contrôle les données soumises,
• la fonction traiter() exécute les actions.

La partie HTML du formulaire est écrite dans le fichier formulaires/{nom}.html. Les 3 fonctions PHP dans le fichier formulaires/{nom}.php et s’appellent précisément :

• formulaires_{nom}_charger_dist(),
• formulaires_{nom}_verifier_dist(),
• formulaires_{nom}_traiter_dist().

Le formulaire s’appelle dans un squelette SPIP par la balise #FORMULAIRE_{NOM}, par exemple #FORMULAIRE_PIPOTIN

Projet exemple : traduire via google

Nous avons besoin d’un formulaire disposant d’un champ texte, dont le contenu sera traduit en anglais en utilisant l’API de Google Translate au moment de la soumission.

HTML

La partie HTML ressemble à çà :

<div class="formulaire_spip formulaire_pipotin"> [<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>] [<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>] <form action="#ENV{action}" method="post"><div> #ACTION_FORMULAIRE{#ENV{action}} <ul> #SET{erreurs,#ENV**{erreurs}|table_valeur{traduire}} <li class="editer_traduire obligatoire[ (#GET{erreurs}|oui)erreur]"> <label for="traduire">Traduire</label> [<span class='erreur_message'>(#GET{erreurs})</span>] <textarea name='traduire' id='champ_traduire'>#ENV{traduire}</textarea> </li> [ #SET{erreurs,#ENV**{erreurs}|table_valeur{traduction}} <li class="editer_traduction[ (#GET{erreurs}|oui)erreur]"> <label for="traduction">Traduction</label> [<span class='erreur_message'>(#GET{erreurs})</span>] <textarea name='traduction' id='champ_traduction'>(#ENV{traduction})</textarea> </li> ] </ul> <p class="boutons"><input type="submit" class="submit" value="<:pass_ok:>" /></p> </div></form> </div>

Analysons le code pour comprendre. Il y a plusieurs éléments. D’une part le code est encadré dans une balise <div> ayant une classe CSS générale « formulaire_spip » et une spécifique « formulaire_XX » :

<div class="formulaire_spip formulaire_pipotin"> … </div>

Dedans, deux lignes servent à afficher les messages de réussite ou d’erreur :

[<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>] [<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>]

Les variables d’environnement « message_erreur » et « message_ok » sont envoyées au squelette via les retour des fonctions PHP…

Ensuite, la description du formulaire ajoute grâce à la balise #ACTION_FORMULAIRE des informations utiles à SPIP pour le traitement du formulaire.

<form action="#ENV{action}" method="post"><div> #ACTION_FORMULAIRE{#ENV{action}} … </div></form>

L’URL de soumission est calculée par SPIP et envoyée par la variable « action » à l’environnement du squelette.

Se trouve ensuite les champs du formulaire, structurés dans un chainage UL / LI. Ils affichent éventuellement des messages d’erreurs.

Les champs sont insérés avec des classes CSS particulières si le champ est obligatoire ou en erreur.

#SET{erreurs,#ENV**{erreurs}|table_valeur{traduire}} <li class="editer_traduire obligatoire[ (#GET{erreurs}|oui)erreur]"> <label for="traduire">Traduire</label> [<span class='erreur_message'>(#GET{erreurs})</span>] <textarea name='traduire' id='champ_traduire'>#ENV{traduire}</textarea> </li>

Pour terminer sur la partie HTML, signalons que la version 1.12 de CFG, à titre expérimental, propose une balise #SAISIE simplifiant l’écriture d’appel des champs de formulaire. Avec, cela donne l’écriture suivante :

[(#SAISIE{textarea,traduire,oui}{label=Traduire})]

Soit au complet, le formulaire HTML donnerait :

<div class="formulaire_spip formulaire_pipotin"> [<p class="reponse_formulaire reponse_formulaire_erreur">(#ENV*{message_erreur})</p>] [<p class="reponse_formulaire reponse_formulaire_ok">(#ENV*{message_ok})</p>] <form action="#ENV{action}" method="post"><div> #ACTION_FORMULAIRE{#ENV{action}} <ul> [(#SAISIE{textarea,traduire,oui}{label=Traduire})] [(#ENV{traduction}|oui) [(#SAISIE{textarea,traduction}{label=Traduction})] ] </ul> <p class="boutons"><input type="submit" class="submit" value="<:pass_ok:>" /></p> </div></form> </div>

Charger

La fonction PHP charger() permet d’envoyer à l’environnement du squelette de formulaire des valeurs par défaut. La fonction retourne un tableau PHP correspondant au contexte de compilation. Mais, si les nom des clés du tableau correspondent à des variables qui ont déjà été soumises (par soumission du formulaire ou via l’URL), alors ce sont ces valeurs que le squelette utilisera pour son contexte.

Pour notre formulaire, nous allons avoir besoin de 2 paramètres, l’un pour recevoir le texte à traduire, l’autre pour retourner le contenu de la traduction.

function formulaires_pipotin_charger_dist() { $contexte = array( 'traduire' => '', 'traduction' => '', ); return $contexte; }

Ici, par défaut les deux paramètres sont laissés vides. Lorsque l’on soumet le formulaire (si l’on a rempli le champ "traduire" dans celui-ci) - et que la fonction vérifier ou traiter indique qu’il faut réafficher la saisie, la gestion de CVT fait que le texte soumis dans le champ "traduire" sera réintroduit automatiquement dans le contexte au chargement du formulaire. On ne perd donc pas les données saisies si une erreur apparaît.

Paramètres d’un formulaire

Il est possible d’envoyer des paramètres lors de l’appel du formulaire dans les squelettes, par exemple :

[(#FORMULAIRE_NOM{parametreA, parametreB})]

Ces deux paramètres sont alors récupérables en tant que paramètres des fonctions Charger, Vérifier et Traiter :

formulaires_nom_charger_dist($parametreA, $parametreB) { ... }

Vérifier

Elle sert à tester les saisies des utilisateurs et à retourner éventuellement des messages d’erreur en cas de problèmes, qui peuvent être spécifiques à un champ de saisie. Pour notre exemple, on peut proposer :

function formulaires_pipotine_verifier_dist() { $erreurs = array(); if (!_request('traduire')) { $erreurs['message_erreur'] = "Vous avez oublié d'écrire ! Votre clavier est cassé ?"; $erreurs['traduire'] = "C'est là dedans qu'on écrit son texte !"; } return $erreurs; }

La fonction vérifier est assez simple : elle retourne un tableau PHP vide s’il n’y a pas d’erreur, un tableau non vide s’il y a une erreur quelconque.

Traiter

C’est la fonction qui s’occupe de tout les traitements que doit exécuter le formulaire lorsque les vérifications sont valides.

Cette fonction retourne un tableau PHP qui peut contenir entre autre les clés "message_ok", "message_erreur", "editable" (si le formulaire doit ou non être réaffiché après le traitement).

Ici, nous devons interroger une page distante de Google et récupérer son résultat. On utilise l’API de SPIP pour cela (recuperer_page) et la fonction de PHP 5.2 pour analyser le JSON (tableau javascript) récupéré.

En cas d’erreur, on le signale ; en cas de réussite, on force l’insertion du texte récupéré dans le prochain chargement du formulaire, avec la fonction de SPIP « set_request() »

// http://ajax.googleapis.com/ajax/services/language/translate?v=1.0&q=hello%20world&langpair=en%7Cit define('URL_GOOGLE_TRANSLATE', "http://ajax.googleapis.com/ajax/services/language/translate"); function formulaires_pipotin_traiter_dist() { // creer l'url selon l'api google $texte = _request('traduire'); $url = parametre_url(URL_GOOGLE_TRANSLATE,'v',"1.0",'&'); $url = parametre_url($url,'langpair','fr|en','&'); $url = parametre_url($url,'q',$texte,'&'); // chargement du texte traduit par google (retour : json) include_spip('inc/distant'); $trad = recuperer_page($url); // attention : php 5.2 $trad = json_decode($trad, true); // true = retour array et non classe // recuperation du resultat si OK if ($trad['responseStatus'] != 200) { return array( "editable" => true, "message_erreur" => "Pas de chance, faux retour de l'ami Google !" ); } // envoi au charger set_request('traduction', $trad['responseData']['translatedText']); // message return array( "editable" => true, "message_ok" => "Et voilà la traduction !", ); }