Si vous travaillez avec le CMS Drupal et que vous souhaitez personnaliser vos formulaires, vous avez probablement entendu parler de Form API Drupal. Dans cet article, nous allons plonger dans les détails de cet outil puissant et flexible, qui vous permet de créer et de manipuler des “forms” personnalisés et de les intégrer facilement à votre site web.
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 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”.
Cette solution compte de nombreux atouts, en voici quelques uns :
Maintenant, rentrons dans le vif du sujet et dans les détails techniques de son fonctionnement.
Voici les différentes étapes à suivre :
Étape 1 : commencez par créer un module personnalisé, il vous permettra de regrouper tout ce qui le concerne (fonctions de rappel, CSS, JavaScript, etc.) dans un seul endroit organisé.
Ajoutez un nouveau dossier dans le répertoire “modules” et un fichier “nom_du_module.info.yml” contenant les informations de votre module (nom, description et version.).
Ensuite, vous définissez une fonction pour votre formulaire en utilisant la syntaxe suivante :
function nom_du_module_nom_de_la_page_de_formulaire_form($form, &$form_state) {
// Le code du formulaire va ici
return $form;
}
Cette fonction doit être nommée en utilisant le nom de votre module, suivi du nom de la page de formulaire (par exemple “my_module_contact_form”). Elle retourne un tableau qui définit les éléments, tels que les boutons et les zones de texte.
Étape 2 : ajoutez des éléments de formulaire en utilisant les fonctions de Form API telles que “form_textfield()”, “form_select()” et “form_submit()” et validez-le.
Ici, il faut ajouter une fonction de validation pour vous assurer que les datas soumises sont correctes.
Pour cela, vous devez ajouter une propriété “#validate” à votre tableau de formulaire qui pointe vers une fonction de validation personnalisée.
Étape 3 : enfin, pour ajouter une fonction de soumission, vous devez ajouter une propriété “#submit” à votre form array qui pointe vers une fonction de soumission personnalisée. Par exemple :
$form[‘#submit’][] = ‘nom_du_module_nom_de_la_page_de_formulaire_submit’;
Une fois que vous avez défini votre formulaire, vous pouvez l’afficher en utilisant une fonction de retour d’appel, telle que “menu_callback()”. C’est fait !
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 :
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”.
À 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.
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.
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 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 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 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 sont des clés qui peuvent être utilisées pour définir des champs ou des groupes de champs dans Form API de Drupal.
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.
Voici quelques-uns des éléments de formulaire les plus couramment utilisés dans Form API de Drupal :
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.
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.
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.
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 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.
Voici trois conseils pour vous accompagner dans votre utilisation et améliorer l’utilisation des Form API Drupal :
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..
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.