Formulaires

Généralité

Un formulaire se compose principalement de :

  1. libellés : le libellé est un texte court associé au champ de saisie pour indiquer le type de donnée à y saisir. Il peut également servir de balise pour afficher une bulle d'information qui décrit plus en détail l'information attendue.
  2. champs de saisie : un champ de saisie est une zone de texte ou de coche qui permet à l'utilisateur d'entrer du texte ou de communiquer une information à envoyer.
  3. boutons d'action : le bouton de soumission est obligatoire pour envoyer et valider les informations saisies, et optionnellement le bouton de réinitialisation du formulaire. D'autres boutons d'action peuvent exister, tels que le bouton d'annulation qui permet d'annuler la saisie ou la modification en cours.

L'analyse de la composition d'un formulaire standard nous amène à définir les besoins suivants :

  1. fournir un maximum d'information à l'utilisateur pour que ce dernier sache exactement ce qu'il a à faire : libellé, bulle d'information, placeholder, un astérisque pour indiquer que le champ de saisie est obligatoire ;
  2. contrôler la valeur saisie attendue dans les champs, ce qui revient à vérifier l'optionalité, la longueur minimale/maximale, le format et/ou le type des données ;
  3. informer l'utilisateur par un message explicatif des données saisies qui ne vérifient pas le contrôle ou la validité des données.

La description des données du formulaire

Prenons par exemple, un simple formulaire de contact composé des champs de différents types :

  1. civilité : 2 boutons radio pour le choix "Madame" ou "Monsieur" ;
  2. prénom : un champ de texte dont la valeur doit vérifier le format d'un prénom ;
  3. email : un champ de texte dont la valeur doit vérifier le format d'un email ;
  4. objet : une liste de sélection d'objets pour le message ;
  5. message : une zone de texte libre.

Le framework adventy propose de décrire les propriétés des champs dans un fichier déclaratif. Ce fichier permet d'automatiser le contrôle de type technique (vs contrôle métier) des données, mais également la génération dynamique HTML des champs dans le formulaire.

Voici notre fichier exemple de déclarations des données :

<?php $this->_formData = array('civilityId' => array('label' => 'Civilité','type' => 'radio','values' => array(2 => 'Madame',1 => 'Monsieur'),'defaultValue' => 0,'helpMessage' => 'Veuillez sélectionner une civilité.','placeholder' => null,'format' => array('value' => '/^[12]$/','message' => 'La civilité est incorrecte.'),'required' => array('value' => true,'message' => 'La civilité est obligatoire.'),'minLength' => array('value' => 0,'message' => null),'maxLength' => array('value' => 1,'message' => 'La civilité est incorrecte.'),'messages' => null),'firstName' => array('label' => 'Prénom','type' => 'text','values' => null,'defaultValue' => null,'helpMessage' => 'Votre prénom.','placeholder' => 'Prénom','format' => array('value' => '/^[\p{L}\'\-\x20]+$/u','message' => 'Le prénom est incorrect. Il ne doit pas contenir de chiffre, de caractères spéciaux et ni de ponctuation.'),'required' => array('value' => true,'message' => 'Le prénom est obligatoire.'),'minLength' => array('value' => 0,'message' => null),'maxLength' => array('value' => 128,'message' => 'Le prénom est limité à 128 caractères.'),'messages' => null),'email' => array('label' => 'E-mail','type' => 'email','values' => null,'defaultValue' => null,'helpMessage' => 'Votre e-mail.','placeholder' => '...@...','format' => array('value' => '/^[a-zA-Z\d\._\-]+@[a-zA-Z\d\-]+(?:\.[a-zA-Z\d_\-]+)*$/','message' => 'Le format de l\'e-mail est incorrect.'),'required' => array('value' => true,'message' => 'L\'e-mail est obligatoire.'),'minLength' => array('value' => 7,'message' => 'L\'e-mail doit comporter au moins 7 caractères.'),'maxLength' => array('value' => 128,'message' => 'L\'e-mail est limité à 128 caractères.'),'messages' => array('SendEmailImpossible' => 'Envoi d\'e-mail impossible. N\'hésitez pas à réessayer ultérieurement.

Soyez assuré(e) que nous mettrons tous les moyens nécessaires pour répondre à votre demande dans les plus brefs délais.

Bien cordialement.
Le Service Technique')),'object' => array('label' => 'Objet','type' => 'select','values' => array(0 => '',1 => 'Renseignement ou information complémentaire',2 => 'Réservation pour une session de formation',3 => 'Devispour un projet en forfait',4 => 'Besoin d\'une ressource en régie',5 => 'Autre'),'defaultValue' => 0,'helpMessage' => 'L\'objet de votre message.','placeholder' => 'Objet du message','format' => array('value' => '/^[1-5]$/','message' => 'L\'objet du message est incorrect.'),'required' => array('value' => true,'message' => 'L\'objet du message est obligatoire.'),'minLength' => array('value' => 0,'message' => null),'maxLength' => array('value' => 1,'message' => 'L\'objet du message est incorrect.'),'messages' => null),'message' => array('label' => 'Message','type' => 'textarea','values' => null,'defaultValue' => null,'helpMessage' => 'Votre message.','placeholder' => 'Bonjour,','format' => array('value' => null,'message' => null),'required' => array('value' => true,'message' => 'Le message est obligatoire.'),'minLength' => array('value' => 7,'message' => 'Le message doit comporter au moins 8 caractères.'),'maxLength' => array('value' => 4096,'message' => 'Le message est trop long. Il est limité à 4096 caractères.'),'messages' => null));?>

La création de ce fichier suit la même règle de nommage que pour les pages statiques/dynamiques, les CSS/JS de page et AOP. En prenant comme exemple le formulaire d'ajout d'un nouvel utilisateur dont la requête est /manager/user/add-user, le fichier déclaratif des données du formulaire serait /application/form/manager/user/add-user.form.php.
Le dossier /application/form/ regroupe donc tous les fichiers déclaratifs des données de formulaire.

Chaque donnée dispose des propriétés suivantes :

PropriétéDescription
label (optionnelle)C'est le libellé ou texte court qui accompagne le champ de saisie pour indiquer à l'utilisateur le type de donnée attendue. Cette propriété est facultative. Par conséquent, la valeur null peut être renseignée.
typeLa propriété type est obligatoire. Elle définit le type attendu de l'information à saisir. Ce type correspond aux éléments de formulaire des balises input, select et textarea.
Les valeurs possibles de la propriété type sont :
  • hidden : champ caché de texte sur une ligne.
  • text : champ de texte libre sur une ligne.
  • password : champ de saisie d'un mot de passe dont la valeur est masquée.
  • tel : champ de texte pour saisir un numéro de téléphone.
  • url : champ de texte permettant la saisie d'un URL.
  • email : champ de texte dédié à la saisie d'un email.
  • radio : bouton radio qui permet de sélectionner une seule valeur parmi un groupe d'autres valeurs.
  • checkbox : case à cocher permettant de cocher ou de décocher une option.
  • date : champ de saisie d'une date avec année, mois et jour.
  • datetime : champ de saisie d'une date et d'une heure (année, mois, jour, heure, minute, seconde, fraction de seconde) avec le fuseau horaire défini sur UTC.
  • datetime-local : champ de saisie d'une date et d'une heure sans fuseau horaire.
  • time : champ de saisie d'une heure (heure, minute, seconde, fraction de seconde) sans fuseau horaire.
  • month : champ de saisie qui permet de saisir un mois et une année sans fuseau horaire.
  • week : champ de saisie d'une année et le numéro de la semaine (de 1 à 53) pendant cette année.
  • number : champ de saisie permettant de saisir un nombre.
  • range : champ de saisie qui permet d'indiquer une valeur numérique comprise entre 2 bornes.
  • color : champ de saisie limité à 7 caractères définissant un code couleur sous le format #rrggbb.
  • search : champ de texte acceptant des termes de recherche.
  • select : liste de séléection unique ou multiple.
  • textarea : zone de texte libre pouvant accepter les retours à la ligne.
values (optionnelle)Liste de valeurs proposées pour les champs de type radio, select. Cette propriété n'a aucune impact pour les autres types de champs. Cette liste est sous forme d'un tableau associatif.
defaultValue (optionnelle)Valeur par défaut affectée au champ à l'initialisation.
helpMessage (optionnelle)Message informatif utilisé en infobulle pour guider l'utilisateur à saisir la donnée attendue.
placeholder (optionnelle)Texte d'information court par défaut dans un champ de saisie. Son rôle est similaire à la propriété helpMessage.
format (optionnelle)Cette propriété renseigne le format attendue du champ de saisie. Le format accepte 2 types de valeur :
  1. un filtre de validation :
    • boolean : reconnaît les valeurs "1", "0", "true", "false", "on", "off", "yes" et "no" comme type booléen.
    • domain : valide un nom de domaine.
    • email : valide un email.
    • float : valide un nombre décimal.
    • int : valide un entier.
    • ip : valide une adresse IP, éventuellement IPv4 ou IPv6.
    • mac : valide la valeur comme une adresse MAC.
    • regexp : valide une expression régulière compatible Perl.
    • url : valide un URL avec ou sans protocole HTTP.
  2. une expression régulière : cette valeur est déterminée par le premier caractère "/" et le dernier caractère "/" (ex : '/^\d{1,3}$/').
requiredLa propriété required n'accepte que 2 valeurs :
  • true pour indiquer que la donnée est obligatoire.
  • false indique que l'information est facultative.
minLength (optionnelle)Propriété indiquant la longueur minimale de la donnée. Un entier est donc attendue.
maxLength (optionnelle)Propriété renseignant la longueur maximale de la donnée. Cette valeur doit être supérieure ou égale à minLength.
messages (optionnelle)Tableau associatif regroupant tous les autres messages d'erreur pouvant être associés à la donnée.

La déclaration de ces propriétés sont obligatoires même si nombreuses ne sont pas utilisées. Dans ce cas, la propriété aura la valeur 0 (zéro) ou null selon son type.

Chaque propriété est accompagnée des données :