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. Le bouton de réinitialisation du formulaire, quant à lui, est optionnel. 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 de sujets 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 => 'Devis  pour 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 :

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 :

• value : valeur du filtre. null ou 0 selon le type si aucun filtre.
• message : message (d'erreur) affiché lorsque la donnée du champ de saisie ne correspond pas au filtre défini dans value. si ce dernier est à null, alors message sera à null aussi.

Programmation Orientée AspectEvènements