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 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 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é Cross-Site Request Forgeries (CSRF) [1]
• Pagination automatique (ou manuelle) des longs formulaires.
• 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 Form_Generic.

[1] Protection contre les attaques de type Cross-Site Request Forgeries (CSRF) : le principe pour corriger cette faille 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 soumis 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

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.

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é.

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é.

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é.

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.

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.

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 '<pre>';
  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);
...