====== Pxxo_Widget_Form ======
Ce widget permet de manipuler des formulaires HTML. Ses fonctionnalités sont les suivantes :
* Chaque champ du formulaire est décrit par un [[:fr:doc:pxxo_widget_input|tableau de paramètres]] et chaque champ possède un identifiant (cf le paramètre **inputs**)
* Premier niveau de gestion des erreurs gérées en interne. Par exemple : champs obligatoires et longueur maximales des champs
* Gestion des erreurs personnalisables par le biais d'une callback utilisateur. (cf le paramètre **validate_callback**)
* Résultats du formulaire renvoyés dans un tableau dont les clés sont nommées (identifiant du champ).
* Modularité des champs : chaque champ est un [[:fr:doc:pxxo_widget_input|widget indépendant]]. Ceci permet de rajouter très facilement un nouveau type de champ et ceci permet de modifier finement l'apparence des champs (thèmes).
* Module de sécurité contre les attaques de type "[[http://fr.wikipedia.org/wiki/Cross-Site_Request_Forgeries|Cross-Site Request Forgeries]]" (CSRF) (( Le principe pour corriger les failles CSRF est d'ajouter un "token" de validité dans chaque formulaire généré. Au moment de générer le formulaire, un token (identifiant aléatoire) est placé dans la session de l'utilisateur et dans le formulaire. Ce token est alors soumit avec le reste du formulaire (en mode "hidden"). Le token reçu est alors comparé à celui présent en session, s'ils sont différents alors c'est une attaque CSRF. Voici un exemple concret d'attaque sur le CMS dotclear : http://ar3av.free.fr/faille-dotclear.php ))
* FIXME Pagination automatique (ou manuelle) des longs formulaires.
* FIXME Gestion des groupes de champs - fieldset (ces groups pourraient être utilisés pour préciser manuellement le découpage pour la pagination)
__Remarque :__ ce widget est le successeur de [[:fr:doc:pxxo_widgets_form_generic|Form_Generic]].
__Observation :__ Les études suivantes ([[http://www.smashingmagazine.com/2008/07/04/web-form-design-patterns-sign-up-forms/|étude part 1]], [[http://www.smashingmagazine.com/2008/07/08/web-form-design-patterns-sign-up-forms-part-2/|étude part 2]]) seraient intéressantes à prendre en compte dans les futures évolutions de l'ergonomie de widget Form.
===== Paramètres du formulaire =====
^ Nom ^ Type ^ Valeur par défaut ^ Description ^
| inputs | Array | array() | Liste des paramètres des champs du formulaire (consultez [[:fr:doc:pxxo_widget_input|la doc des différents types de champs]] pour connaître leur paramètres spécifiques). |
| method | String | 'post' | Méthode HTTP de soumission du formulaire ('post' ou 'get'). |
| action | String | "" | Permet de forcer l'url de soumission du formulaire. Dans la plupart des cas la chaîne vide (défaut) est suffisante car le formulaire sera soumit sur lui même. |
| label_width | String | '15em' | La largeur de la première colonne. Utile seulement avec le thème 'float'. |
| required_marker | String | '* ' | Les caractères qui seront utilisés pour signaler qu'un champ est obligatoire. |
| separator_marker | String | ' : ' | Les caractères qui seront utilisés pour séparer les textes de leurs champs. |
| submit_label | String | - | La chaîne de caractères que le bouton submit doit utiliser |
| validate_callback | [[http://www.php.net/callback#language.types.callback|callback]] | null | Callback de validation par défaut. Si cette callback est définit, elle sera appelée N fois pour la validation des N champs qui n'ont pas eux même de callback définit. Pour connaître les paramètres attendus par la callback, référez vous à la documentation des [[:fr:doc:pxxo_widget_input|widget Input]]. |
| submit_callback | [[http://www.php.net/callback#language.types.callback|callback]] | null | Callback appelée //une seule fois// lorsque le formulaire est soumis et validé (n'est pas appelée si le formulaire contient des erreurs). Par exemple, vous pouvez utiliser cette callback pour enregistrer les champs soumis dans une base de données. L'unique paramètre de cette callback est une référence vers le widget Form courant. |
| csrf_validation | Bool | true | Permet d'activer/désactiver la protection contre les attaques CSRF. |
__Remarque :__ Le paramètre ''validate_callback'' respecte le standard PHP en la matière. Il peut donc contenir soit le nom d'une fonction, soit un tableau dont le premier paramètre est l'instance de l'objet et le second le nom de la méthode à appeler. Pour plus d'informations consultez la documentation officielle de PHP : http://www.php.net/callback#language.types.callback.
===== Méthodes disponibles =====
==== getInputArray ====
__Prototype :__ ''array getInputArray($id = null)''
* Sans paramètre, cette méthode retourne la liste des paramètres des différents champs indexés avec l'id des champs.
* Elle peut s'utiliser avec un paramètre qui doit être l'identifiant d'un champ. Les paramètre de ce champ sont alors retournés. Si l'identifiant ne correspond à aucun champ, un tableau vide est retourné.
==== getInputWidget ====
__Prototype :__ ''array getInputWidget($id)''
Le paramètre ''$id'' doit correspondre à l'id d'un champ. L'instance du widget Input correspondant est alors retournée. Si l'identifiant ne correspond à aucun champs, ''NULL'' est retourné.
==== getResult ====
__Prototype :__ ''mixed getResult($id = null)''
* Sans paramètre, cette méthode retourne la liste des valeurs soumises des différents champs. Cette liste de valeurs est indexée par les id des différents champs. Si le formulaire n'est pas encore soumis, NULL est retourné.
* Elle peut s'utiliser avec un paramètre qui doit être l'identifiant d'un champ. La valeur soumise de ce champ est alors retournée. Si l'identifiant ne correspond à aucun champ ou que le formulaire n'est pas encore soumis, NULL est retourné.
==== getErrors ====
__Prototype :__ ''array getErrors()''
Retourne la liste des éventuelles erreurs du formulaire (chaînes de caractères). Attention, les erreurs ne peuvent se produire qu'au moment où le formulaire est soumis et validé. En général le développeur n'a pas besoin d'appeler cette méthode car le formulaire se charge lui même d'afficher les messages d'erreurs.
==== hasError ====
__Prototype :__ ''boolean hasError()''
Retourne true si le formulaire possède des erreurs, false sinon. Cette méthode est très liée à la méthode ''getErrors''.
===== Exemples =====
Un formulaire très simple avec un unique champ texte :
require_once "Pxxo/Widget/Form.php";
$params['inputs'] = array();
$params['inputs'][] = array('id' => 'id_de_mon_test2',
'label' => 'Mon champ text',
'type' => 'text',
'size' => 50,
'required' => true,
);
$o = new Pxxo_Widget_Form($params);
...
if ($o->getMode() == 'submit')
{
echo '';
echo 'print_r($o->getErrors());'."\n";
print_r($o->getErrors());
echo 'print_r($o->getResult());'."\n";
print_r($o->getResult());
}
Un formulaire avec une callback de validation personnalisée qui va se charger de vérifier que la valeur saisie est bien un entier positif :
require_once "Pxxo/Widget/Form.php";
function my_validate_callback($input)
{
$errors = array();
if (!is_numeric($input['result']) || $input['result'] < 0)
$errors[] = 'Ce champ doit impérativement être un entier positif';
return $errors;
}
$params['inputs'] = array();
$params['inputs'][] = array('id' => 'id_de_mon_nombre',
'label' => 'Entrez un entier positif',
'type' => 'text',
'validate_callback' => 'my_validate_callback',
);
$o = new Pxxo_Widget_Form($params);
...
Un formulaire avec une callback de validation personnalisée qui va se charger de vérifier que les deux mots de passes saisis sont identiques :
require_once "Pxxo/Widget/Form.php";
function my_validate_callback2($input, $form)
{
$errors = array();
$input_mdp = $form->getInputArray('id_de_mon_mdp');
if ($input_mdp['result'] != $input['result'])
$errors[] = 'Les mots de passe doivent être identique !';
return $errors;
}
$params['inputs'] = array();
$params['inputs'][] = array('id' => 'id_de_mon_mdp',
'label' => 'Entrez votre mot de passe',
'type' => 'password',
'size' => 10,
'minlength' => 4,
);
$params['inputs'][] = array('id' => 'id_de_mon_mdp2',
'label' => 'Confirmez votre mot de passe',
'type' => 'password',
'size' => 10,
'minlength' => 0,
'validate_callback' => 'my_validate_callback2',
);
$o = new Pxxo_Widget_Form($params);
...
Un formulaire avec une callback de validation par défaut qui sera appelée pour tous les champs. Ici on va simplement vérifier que les champs 'text' et 'textarea' contiennent bien les bons caractères.
require_once "Pxxo/Widget/Form.php";
$params = array();
function global_validate_callback($input)
{
$errors = array();
if (!preg_match('/[[:alpha:]]+/i',$input['result']))
$errors[] = 'Ce champ doit contenir impérativement une chaîne de caractères';
return $errors;
}
$params['validate_callback'] = 'global_validate_callback';
$params['inputs'] = array();
$params['inputs'][] = array('id' => 'id_de_mon_text',
'label' => 'Un input text',
'type' => 'text',
'value' => 'un texte'
);
$params['inputs'][] = array('id' => 'id_de_mon_textarea',
'label' => 'Un input textarea',
'type' => 'textarea',
'size' => array(30,5),
'value' => 'un texte long'
);
$o = new Pxxo_Widget_Form($params);
...