Form API, un outil riche et flexible
Vous recherchez une solution simple et efficace pour créer et personnaliser un type de form sur votre site web ? La bonne nouvelle, c’est que vous l’avez déjà.
✚ Form API, comment ça fonctionne ?
Form API est directement intégré à Drupal. Il n’y a donc rien à installer, rien à télécharger. Le processus de création d'un formulaire nécessite cependant quelques compétences techniques.
Il faut commencer par la définition d'un tableau composé de sa structure (“form array”) et des éléments qu’il contient, par exemple, les champs de saisie (“field”), les boutons et les messages envoyés aux utilisateurs.
Les développeurs peuvent spécifier des propriétés pour chaque élément : un title, des libellés, des valeurs par défaut et des validations.
Ensuite, le tableau est envoyé à une fonction spécifique (“function”) de Form API qui va générer le formulaire HTML à partir d’un form array.
Une fois que le formulaire est affiché sur la page, les utilisateurs peuvent le remplir et soumettre leurs réponses. Form API récupère les informations et effectue une validation pour s'assurer qu’elles sont correctes et sécurisées.
Si le formulaire contient des erreurs, les messages d'erreur appropriés sont immédiatement affichés.
Dans le cas contraire, elles sont traitées c’est-à-dire enregistrées dans la base de données ou envoyées par e-mail.
Il est possible de gérer de l'état (“state”) des formulaires en utilisant≈
Elles permettent aux développeurs de stocker et de récupérer l'état des éléments de formulaire ou de modifier dynamiquement leur état en fonction des actions de l'utilisateur.
Par exemple, s’il figure un champ (“field”) "Pays" et un champ "Ville", il est possible de cacher le champ "Ville" tant que l'utilisateur n'a pas sélectionné un pays, dans ce cas, l'état du champ "Ville" est dépendant de l'état du champ "Pays".
✚ Les avantages à l'utilisation de Form API
Cette solution compte de nombreux atouts, en voici quelques uns :
- La flexibilité : il est possible d’ajouter des champs de saisie, des boutons et des messages d'erreur personnalisés, et de modifier les formulaires existants pour les faire correspondre à la très grande majorité de vos besoins. C’est toute la richesse de cette solution.
- La sécurité : ce n’est pas un point négligeable ! Form API vous permet de vous protéger contre les attaques CSRF et les injections de code malveillant.
- Une intégration facile : ajouter le form dans un contenu ou au sein d’un bloc se fait en quelques minutes.
- La personnalisation : c’est également un point fort. Les développeurs peuvent répondre précisément aux demandes de leurs clients, en personnalisant l'apparence et le comportement des formulaires via des thèmes ou des fichiers CSS.
Vous avez un projet ? Besoin de conseils ?
Les différents types de champs à votre disposition
Form API offre une grande variété de types de “fields” pour la création de formulaires dans Drupal. Voici une liste des types de ceux couramment utilisés :
- textfield : un champ de saisie de texte simple
- textarea : une zone de texte multi-lignes pour les entrées de texte plus longues
- select : un menu déroulant avec des options prédéfinies
- radios : une liste de boutons radio pour les options mutuellement exclusives
- checkboxes : une liste de cases à cocher pour les options non mutuellement exclusives
- date : un champ de sélection de date avec un calendrier interactif
- file : un champ de sélection de fichier pour les téléchargements de fichier
- email : un champ de saisie de texte pour les adresses e-mail
- password : un champ de saisie de texte pour les mots de passe
Il existe également des types plus avancés pour les sélections multiples, la recherche, la géolocalisation, etc.
Vous pouvez également créer votre propre type de champ personnalisé en étendant la classe "WidgetBase".
Comment encapsuler les champs
À noter : les fields peuvent être encapsulés dans des groupes ou des ensembles à l'aide de la fonction fieldset afin de mieux organiser le formulaire. La syntaxe de la fonction fieldset est la suivante :
$form['nom_du_groupe'] = [
'#type' => 'fieldset',
'#title' => 'Titre du groupe',
'#collapsible' => TRUE, // Facultatif : permet de rendre le groupe pliable
'#collapsed' => TRUE, // Facultatif : permet de rendre le groupe plié par défaut
// Les fields du groupe sont déclarés ici];
Il est également possible de créer des groupes imbriqués pour une organisation plus complexe. Les groupes imbriqués sont déclarés de la même manière que les principaux, mais ils sont placés à l'intérieur de l'array du groupe parent. Voici un exemple de code pour encapsuler des champs dans un groupe :
$form['mes_champs'] = [
'#type' => 'fieldset',
'#title' => 'Mes champs',
'#collapsible' => TRUE,
'#collapsed' => TRUE,'nom' => [
'#type' => 'textfield',
'#title' => 'Nom',
'#required' => TRUE, ],'email' => [
'#type' => 'email',
'#title' => 'Adresse e-mail',
'#required' => TRUE, ],];
Dans cet exemple, deux champs textfield et email sont encapsulés dans le groupe mes_champs. Le groupe est pliable et plié par défaut. Les deux sont obligatoires.
✚ Comment récupérer la valeur des champs ?
Pour récupérer les valeurs d'un formulaire soumis, vous pouvez utiliser l'objet FormState. L'objet FormState contient également d'autres informations sur l'état du formulaire. Pour récupérer la valeur d'un champ, vous pouvez utiliser la méthode getValue() de l'objet FormState.
Il est également possible de récupérer toutes les valeurs soumises en une seule fois en utilisant la méthode getValues() de l'objet FormState.
✚ Gérer l'affichage : les différentes approches possibles
L'affichage d'un formulaire est géré par le thème du site web. Pour le personnaliser, vous pouvez créer un modèle de thème en utilisant les suggestions de Drupal. Il existe d’autres manières de procéder.
L'approche render array
L'approche Render Array est une autre façon de gérer l'affichage des éléments dans Drupal. Elle permet de contrôler la manière dont les éléments HTML sont générés en utilisant un tableau PHP multidimensionnel appelé un "Render Array".
Le Render Array est utilisé pour décrire ceux qui doivent être affichés, y compris les formulaires, les blocs, les champs, les blocs de texte, les menus et plus encore. Chaque élément dans le Render Array est défini par un tableau qui contient des clés et des valeurs. Elles décrivent ses propriétés et les valeurs contiennent les informations à afficher.
L'approche theming
L'approche Theming est une façon de personnaliser l'apparence des éléments dans Drupal en utilisant des fichiers de thème. Les fichiers de thème contiennent du code HTML, CSS et PHP qui décrivent l'apparence des éléments. Cette approche permet aux développeurs de la personnaliser sans avoir besoin de modifier le code source du module.
La gestion des champs en AJAX
La gestion en AJAX (Asynchronous JavaScript and XML) est une fonctionnalité qui permet de mettre à jour une partie de la page sans avoir besoin de la recharger entièrement. Cette fonctionnalité peut être très utile pour les formulaires qui ont des champs qui dépendent d'autres.
Pour ajouter la gestion des champs en AJAX à un formulaire, il est possible d'utiliser la fonction "ajax_form_callback" de Drupal. Cette fonction permet de définir une fonction de rappel qui sera appelée lorsqu'un champ est modifié. Elle peut charger des datas supplémentaires et mettre à jour les champs du formulaire.
✚ Les éléments de formulaire dans Form API
Les éléments de formulaire sont des clés qui peuvent être utilisées pour définir des champs ou des groupes de champs dans Form API de Drupal.
Comment ajouter des éléments de formulaire personnalisés avec Form API
Voici les étapes à suivre.
✚ Étape 1 : définissez une nouvelle fonction pour l'élément de formulaire personnalisé :
function nom_module_element_form_mon_element($element, &$form_state, $complete_form) {
// Les éléments de votre formulaire personnalisé return $element;}
✚ Étape 2 : dans votre fonction de génération, ajoutez le nouvel élément en utilisant la clé :
'#type' et la valeur personnalisée que vous avez définie :
$form['nom_element'] = array( '#type' => 'mon_element',);
✚ Étape 3 : enregistrez votre nouvelle fonction d'élément de formulaire au moyen d’un hook, comme suit : hook_element_info() :
Une fois ces étapes effectuées, vous pouvez utiliser votre nouvel élément de formulaire personnalisé dans n'importe quel formulaire en utilisant la clé '#type' et la valeur que vous avez définie pour votre nouvel élément de formulaire.
Les éléments de formulaire les plus couramment utilisés
Voici quelques-uns des éléments de formulaire les plus couramment utilisés dans Form API de Drupal :
- type comme nous l’avons vu plus haut.
- title : cette clé est utilisée pour définir le titre du champ. Le titre est généralement affiché à côté du champ pour donner des instructions ou des informations sur le champ.
- description : cette clé est généralement affichée sous le champ pour donner des informations supplémentaires.
- default_value qui sert à définir la valeur par défaut du champ.
- required pour définir si le champ est obligatoire ou facultatif.
- size pour définir la taille du champ de texte.
- options pour définir les options pour les fields de type liste déroulante, cases à cocher et boutons radio.
- maxlength' pour définir le nombre maximum de caractères autorisés dans le champ.
Ces éléments de formulaire peuvent être combinés pour créer des fields de formulaire personnalisés avec des propriétés spécifiques pour chaque champ.
✚ Les soumissions de formulaire dans Form API
Une fois que vous avez créé votre formulaire, vous devez définir la logique de soumission et de validation. Voyons cela de plus près.
Comment traiter les données soumises par un formulaire
Voici les étapes à suivre pour ajouter des éléments de formulaire personnalisés avec Form API :
✚ Étape 1 : définissez une nouvelle fonction pour l'élément de formulaire personnalisé comme suit :
function nom_module_element_form_mon_element($element, &$form_state, $complete_form) {
// Les éléments de votre formulaire personnaliséreturn $element;}
✚ Étape 2 : dans votre fonction de génération de formulaire, ajoutez le nouvel élément en utilisant la clé '#type' et la valeur personnalisée que vous avez définie :
$form['nom_element'] = array( '#type' => 'mon_element',);
✚ Étape 3 : enregistrez votre nouvelle fonction d'élément de formulaire dans le hook_element_info() :
function nom_module_element_info() {$elements = array();$elements['mon_element'] = array
( '#input' => true, '#process' => array('nom_module_element_form_mon_element'), );return $elements;}
Une fois ces étapes effectuées, vous pouvez utiliser votre nouvel élément de formulaire personnalisé dans n'importe quel formulaire en utilisant la clé '#type' et la valeur que vous avez définie.
Comment valider les données soumises d'un formulaire
Pour faire cela, vous devez créer une fonction de validation. Une fois encore, on vous montre le chemin :
✚ Étape 1 : dans votre fonction de génération de formulaire, ajoutez la clé '#validate' pour indiquer quelle fonction doit être appelée pour sa validation :
$form['#validate'] = array('nom_module_validate_function');
✚ Étape 2 : créez une nouvelle fonction pour valider les données soumises en prenant deux paramètres : $form et &$form_state :
function nom_module_validate_function($form, &$form_state) { // Validation des data soumises}
✚ Étape 3 : dans la fonction de validation du formulaire, vous pouvez accéder aux données soumises par l'utilisateur à l'aide de la variable $form_state['values']. Elle contient un tableau de toutes les valeurs soumises dans le formulaire.
✚ Étape 4 : dans la fonction de validation du formulaire, vous pouvez ajouter des règles de validation en utilisant la méthode drupal_form_error(). Cette méthode prend deux paramètres : le nom de l'élément de formulaire à valider et un message d'erreur.
✚ Étape 5 : Si le formulaire ne passe pas la validation, le message d'erreur sera affiché à côté de l'élément concerné. S’il passe la validation, la fonction de soumission du formulaire sera appelée pour traiter les données soumises.
✚ ConfirmFormBase pour confirmer une action
ConfirmFormBase est une classe de Form API qui permet de créer des formulaires pour confirmer une action avant de la réaliser. Elle est souvent utilisée pour les actions qui ont un impact important sur le site, comme la suppression d'un contenu ou d'un utilisateur.
Cette classe hérite de FormBase, ce qui signifie qu'elle a accès à toutes les fonctionnalités de Form API, mais elle fournit également des méthodes spécifiques pour gérer la confirmation de l'action.
Avec ConfirmFormBase, il est possible de personnaliser le texte de confirmation, les boutons de soumission et d'annulation, ainsi que les messages d'erreur.
Les bonnes pratiques à connaître
Voici trois conseils pour vous accompagner dans votre utilisation et améliorer l’utilisation des Form API Drupal :
- Utilisez le système de cache pour améliorer les performances de votre site, cela peut réduire considérablement le temps de chargement.
- Évitez de dupliquer du code en utilisant des éléments de formulaire réutilisables et en regroupant les éléments de formulaire similaires dans des fonctions.
- Utilisez les fonctions de validation et de soumission de Form API pour valider les données et traiter les soumissions. Ne traitez pas les datas soumises directement dans la fonction de construction de formulaire.
✚ Comment concevoir des formulaires conviviaux pour les utilisateurs
Nous avons tous eu à remplir des formulaires et nous savons à quel point l’exercice peut se révéler dissuasif et ennuyeux. Mettez-vous à la place de votre client et évitez d’accumuler les questions. Tenez-vous en au strict nécessaire. Un formulaire = un usage.
Vous pouvez également essayer de lui faciliter la tâche en favorisant l’autocomplétion ou les suggestions au maximum. Un formulaire abandonné en cours de route est un formulaire qui ne sert à rien..
Comment intégrer Form API dans une stratégie de développement Drupal réussie
Les fonctionnalités offertes par l’outil ne sont pas des stratégies en tant que telles. Avant de concevoir un formulaire, prenez le temps d’analyser l’usage qui sera fait des informations. Qu’avez-vous réellement besoin de savoir ? N’y a t-il pas des questions que vous pourriez retirer ?
À l’inverse, disposez-vous bien de toutes les informations afin qu’elles puissent être utilisées réellement par la suite. Prenez le temps de vous poser ces questions (avec le reste de l’équipe !).
Et par ailleurs, nos experts seront ravis d’échanger avec vous sur ces sujets.