Réaliser un formulaire de contact avec gestion d'erreurs et validation de données grâce au framework WdElements

Dans un article précédent nous avions vu comment générer des éléments HTML grâce à la classe WdElement, il est temps de mettre tout cela en pratique en concevant un formulaire de contact qui nous permettra par ailleurs de découvrir quelques une des fonctionnalités de la classe WdForm, comme la gestion des erreurs et la validation des données.

Le lien suivant vous permettra de télécharger le code de démonstration :

Télécharger le code de démonstration (37ko).

L'archive contient des versions minimales des frameworks WdCore et WdElements ainsi que deux exemples de gestion du formulaire : une somme tout classique, et une autre par enregistrement et validation ultérieure. Avant de voir la différence entre ces deux types de gestion, voyons ce que la classe WdForm a à offrir.

Présentation de la classe WdForm

Le propos de la classe WdForm est de créer des formulaires, gérer les valeurs des éléments de ces formulaires et éventuellement les erreurs de validation. Comme nous allons le voir, tout cela se fait assez simplement.

Préambule

Pour les besoins de la démonstration, nous utiliserons la classe Wd2CForm, une des sous-classes de WdForm, qui permet de créer simplement des formulaires sur deux colonnes – une pour les étiquettes des éléments et l'autre pour les éléments – là où la classe WdForm se contente de concaténer le code HTML de ses éléments.

Il existe une autre sous-classe à la classe WdForm, la classe WdTemplatedForm, qui permet de créer des formulaires en utilisant des gabarits HTML, tout en conservant les fonctionnalités de la classe WdForm. Quelle que soit la classe, les formulaires sont conçus de manière similaire.

Créer un formulaire avec la classe WdForm

Pour créer un formulaire il suffit de définir les éléments du formulaire dans un tableau associatif en utilisant l'attribut WdElement::T_CHILDREN.

Les étiquettes des éléments sont définies en utilisant l'attribut WdForm::T_LABEL. Les éléments obligatoires sont indiqués en utilisant l'attribut WdElement::T_MANDATORY. On notera que certains éléments demandent une validation des données saisies. Par exemple, l'élément email définit la fonction de rappel WdForm::validate_email afin de s'assurer que sa valeur est une adresse e-mail valide :

<?php

$form = new Wd2CForm
(
    array
    (
        WdElement::T_CHILDREN => array
        (
            'gender' => new WdElement
            (
                WdElement::E_RADIO_GROUP, array
                (
                    WdForm::T_LABEL => 'Gender',
                    WdElement::T_OPTIONS => array('@genders.mrs''@genders.miss''@genders.mr'),
                    WdElement::T_MANDATORY => true
                )
            ),

            'lastname' => new WdElement
            (
                WdElement::E_TEXT, array
                (
                    WdForm::T_LABEL => 'Lastname',
                    WdElement::T_MANDATORY => true
                )
            ),

            'firstname' => new WdElement
            (
                WdElement::E_TEXT, array
                (
                    WdForm::T_LABEL => 'Firstname',
                    WdElement::T_MANDATORY => true
                )
            ),

            'company' => new WdElement
            (
                WdElement::E_TEXT, array
                (
                    WdForm::T_LABEL => 'Company'
                )
            ),

            'email' => new WdElement
            (
                WdElement::E_TEXT, array
                (
                    WdForm::T_LABEL => 'E-Mail',
                    WdElement::T_MANDATORY => true,
                    WdElement::T_VALIDATOR => array(array('WdForm''validate_email'))
                )
            ),

            'message' => new WdElement
            (
                'textarea', array
                (
                    WdForm::T_LABEL => 'Your message',
                    WdElement::T_MANDATORY => true
                )
            ),

            new WdElement
            (
                WdElement::E_SUBMIT
            )
        )
    )
);

On notera que les noms des éléments peuvent être passés en utilisant les clés du tableau associatif défini par l'attribut WdElement::T_CHILDREN. On obtiendrait le même résultat en définissant l'attribut name de chaque objet, pourtant la méthode utilisée ici est recommandée. Dans un environnement où l'on utilise l'héritage pour construire des formulaires, l'utilisation d'une clé, permet de remplacer ou de supprimer simplement un élément avant de renvoyer le tableau associatif final.

Quoi qu'il en soit, vous devriez obtenir le formulaire suivant :

Contact : Vide

Les étiquettes des éléments

Comme nous l'avons vu plus haut, il s'agit d'un tableau avec deux colonnes : une pour les étiquettes des éléments, et l'autre pour les éléments.

L'étiquette de l'élément est définie par l'attribut WdForm::T_LABEL, à ne pas confondre avec l'attribut WdElement::T_LABEL qui est utilisé pour créer un label autour d'un élément. L'attribut WdElement::T_MANDATORY est également pris en compte lors de la génération de l'étiquette. S'il est vrai, une astérisque est ajoutée pour indiquer que l'élément est obligatoire.

Le code HTML suivant est généré pour l'étiquette de l'élément Civilité :

@html html@

Styliser les étiquettes des éléments

Le style de l'étiquette de l'élément peut facilement être ajusté à notre guise. On utilisera par exemple form.wdform label.mandatory pour cibler l'étiquette d'un élément obligatoire, form.wdform label sup pour styliser l'astérisque ou form.wdform label span.separator pour faire disparaitre les deux points (:).

À noter que les étiquettes définies par l'attribut WdForm::T_LABEL sont traduites par le système d'internationalisation du framework WdCore. Cette fonctionnalité utilisée dans la démonstration, permet de traduire un même formulaire dans n'importe quelle langue. Le système d'internationalisation fera sans doute l'objet d'un prochain article.

Notre formulaire est prêt à accueillir les données de nos visiteurs. Avant de passer à la validation et à la gestion des erreurs, voyons comment remplir notre formulaire avec des données. Au cas où la validation du formulaire échoue, cela permet de présenter au visiteur les données qu'il avait saisi. Il pourra ainsi les corriger au lieu de tout saisir à nouveau.

Remplir un formulaire avec des données

Le remplissage des formulaires est très simple grâce à la classe WdForm. Il suffit pour cela d'utiliser l'attribut WdForm::T_VALUES pour définir les valeurs de tous les éléments qui constituent notre formulaire, aussi profond soient-ils dans l'arbre d'éléments, nous évitant le fardeau de définir les valeurs des attributs value, checked ou autre de chaque élément de notre formulaire :

<?php

$form = new Wd2CForm
(
    array
    (
        WdForm::T_VALUES => $_POST,

        WdElement::T_CHILDREN => array
        (
        )
    )
);

Par défaut, la classe WdForm créée des formulaires de type POST, c'est pourquoi nous utilisons $_POST comme source de données pour les valeurs de nos éléments. Pour créer un formulaire de type GET, il aurait suffit de définir l'attribut method avec la valeur get. Auquel cas nous aurions utilisé $_GET comme source de données.

Validation des données d'un formulaire

Puisque chaque élément du formulaire définit s'il est obligatoire et éventuellement une fonction de rappel pour la validation de sa valeur, la gestion des erreurs et la validation des données se fait très simplement. La méthode validate() permet de valider notre formulaire contre n'importe qu'elle source de données :

<?php

if ($form->validate($_POST))
{
    echo "<p><strong>le formulaire est valide</strong></p>";
}

À noter que le formulaire lui-même peut être validé. Pour cela, et comme pour les éléments du formulaire, puisque la classe WdForm est une sous classes de WdElements, il suffit de définir une fonction de rappel avec l'attribut WdElement::T_VALIDATOR. Cette fonction de rappel sera appelée une fois les éléments du formulaire validés pour terminer la validation du formulaire.

Gestion des erreurs liées aux données

Lors de la validation des données, les erreurs sont collectées dans la session en utilisant le nom du formulaire pour référence. Ainsi, lorsque le formulaire est transformé en code HTML, les erreurs sont récupérées de la session pour être affichées à l'utilisateur. Pour cela, un élément ul ayant pour classe missing est ajouté en tête du formulaire, avec tous les messages d'erreur collectés lors de la validation. Par ailleurs, une classe missing est ajoutée à tous les éléments ayant généré des erreurs. Ainsi, si le visiteur envoie le formulaire sans rien saisir, le formulaire suivant lui sera présenté :

Contact : Manquants

Si le visiteur rempli quelques champs mais que certains sont invalides, le formulaire suivant lui sera présenté :

Contact : Validation

À noter que si le formulaire n'est pas nommé, un nom automatique est généré. Par exemple : form-autoname-1.

Enregistrer un formulaire pour une validation ultérieure

Il est possible d'enregistrer un formulaire en session pour le valider ultérieurement. L'enregistrement en session présente deux avantages : une fonction unique peut valider n'importe quel formulaire, et un formulaire généré ne peut pas être posté deux fois.

Pour sauvegarder un formulaire on utilise la méthode save() :

<?php

$form->save();

echo $form;

À noter que ce n'est pas tout le formulaire qui est enregistré en session, mais seulement les informations nécessaires à sa validation ultérieure.

Une fonction unique pour la validation des formulaires

Comme nous l'avons vu plus haut, ce sont les éléments du formulaire qui définissent leur validation. Puisque ces informations sont enregistrées en session, une fonction unique peut être utilisée pour valider n'importe quel formulaire :

<?php

$form = WdForm::load($_POST);

if ($form && $form->validate($_POST))
{
    echo "<p><strong>le formulaire est valide</strong></p>";
}

Des formulaires uniques

Parce qu'une clé unique est générée pour chaque formulaire enregistré, un même formulaire ne peut être utilisé deux fois. Le formulaire doit être généré (ainsi que la clé qui l'accompagne) pour être posté. Cela permet d'éviter les erreurs de double-envoie lorsque l'utilisateur joue un peu trop avec la touche de rafraichissement ou l'historique de son navigateur. Un autre effet est de réduire le spam, parce qu'une clé de formulaire est nécessaire pour que les données soient validées, impossible d'envoyer directement des données sans avoir au préalable généré un formulaire pour obtenir une clé.

À vous de jouer

Dans l'archive que je vous ai confectionné vous trouverez trois fichiers à la base du dossier :

  • form.php contient l'objet utilisé pour créer le formulaire.
  • index.php présente l'utilisation classique du formulaire.
  • saved.php présente l'utilisation par enregistrement du formulaire.

Cela fait beaucoup d'informations d'un coup, mais j'espère avoir été assez clair, ce qui n'est pas toujours évident. N'hésitez pas à laisser un message si vous avez besoin de plus de précisions.

Conclusion

La classe WdForm apporte de très nombreuses fonctionnalités qui peuvent vous économiser des heures de travail. L'approche objet du framework WdElements vous permet de faire ce que vous voulez avec les objets, comme ajouter vos propres éléments ou de différentes méthodes de validation.

Cela fait un an que le framework ne subit plus de modifications profondes, ce qui est assez étonnant quand on connait mon perfectionnisme. Je pense qu'il est arrivé à une bonne maturité, et c'est peut être pour cela que je me risque à vous le présenter, en espérant qu'il vous soit utile.

Laisser un commentaire

Pas de commentaire