close

Découvrez nos offres pour faire du digital le levier de votre croissance !

download
Modèles

Téléchargez le Guide Ultime de gestion de projet digitale pour vous aider à piloter vos transformations et faire les bons choix !

Image mise en avant pour l'article

Drupal Webform Handlers : comment créer un gestionnaire personnalisé ?

20 mars 2023
Que vous soyez un développeur chevronné ou un novice dans le monde de Drupal, cet article vous fournira une meilleure compréhension de ce que sont les gestionnaires personnalisés de Webform (webform handlers) et comment peuvent-ils améliorer la façon dont vous gérez les soumissions de formulaire sur votre site Web Drupal.


Lors de la création ou de la refonte d'un site Web, l'expérience utilisateur est au coeur du projet. De nombreux facteurs sont pris en compte, mais bien souvent l'optimisation des formulaires est négligée. Pourtant, le formulaire est un composant quasiment indispensable à tout bon site Web. Il est le meilleur moyen d'obtenir des informations sur vos clients potentiels et d'entretenir indirectement une relation avec eux. L'objectif étant souvent d'amener les utilisateurs sur vos canaux.

Perfectionner l'expérience utilisateur de son site Web, sans consacrer du temps aux formulaire Web, pourrait engendrer des interactions complexes et frustrantes. Mais alors, en quoi le module Webform de Drupal contribue à la création et la gestion de formulaire ?

Comment utiliser les WebformHandlers dans Drupal ? Sur la photo, nous apercevons un développeur web derrière ses écrans.

Le module Webform, qu'est-ce que c'est ?

Le module Webform est un générateur de formulaires Open Source et un gestionnaire de soumission pour Drupal. C'est une autre façon de créer et de gérer les formulaires. (À lire aussi, notre article sur la form API de Drupal)

Il fournit les fonctionnalités attendues d'un générateur de formulaires, combinées à la flexibilité et à l'ouverture de Drupal.

Pour simplifier, il permet de :

  • Créer un nouveau formulaire Web ou dupliquer un modèle existant,
  • Publier le formulaire Web en tant que page, nœud ou bloc,
  • Recueillir les soumissions,
  • Envoyer des confirmations et des notifications,
  • Examiner les soumissions en ligne,
  • Télécharger les soumissions au format CSV.

Et tout ça juste au clique... pas besoin de coder. 🤗

Le module Webform apporte de la flexibilité et une certaine liberté. Il possède également un certain nombre de fonctionnalités prêtes à l’emploi, comme :

  • La création de modèle de formulaires,
  • La possibilité de créer des formulaire à plusieurs étapes,
  • De définir et de gérer des conditions diverses,
  • Des validations de formulaire
  • Etc.

À toutes ces fonctionnalités, il sera possible d'intégrer différents plugins afin d’élargir le champs des possibilités. (Pour en savoir plus sur les plugins, je vous invite à lire cet article : À la découverte des plugins sur Drupal)

 

 

Mais alors... les Webform Handlers, c'est quoi ?

Une question, souvent posée, est de savoir comment utiliser les données de soumission de formulaire Web pour effectuer une tâche une fois le formulaire soumis. Cela peut aller de la création d'un enregistrement via une API tierce ou de toucher à une autre partie de Drupal compte tenu des données de soumission.

C’est là que les « handlers » rentrent en actions. Ce sont ces derniers qui vont utiliser les données soumises par le formulaire et gérer un certain nombre d’actions voulues après cette soumission.

Il existe une multitude de gestionnaires déjà intégrer au module Webform. Mais il est également possible de créer notre propre gestionnaire custom afin d’appliquer une logique propre à une problématique de notre site Web.

 

Comment créer son gestionnaire de formulaire personnalisé ?

Ici, je vais vous montrer comment créer son propre gestionnaire post soumission, répondant à une problématique simple que j’ai rencontré lors d’un projet Web.

 

La problématique rencontrée

Sur un projet utilisant Drupal commerce, nous avions un site internet avec plusieurs boutiques distinctes, et un seul formulaire de contact (géré via Webform) regroupant à la fois des questions liées au site lui-même, mais également des questions concernant le paiement pour une boutique en particulier.

Le but de ce formulaire était donc de dispatcher les différentes soumissions (envoi de courriel) selon la raison de l’utilisation du formulaire :

  • Si la soumission concernait le site, il fallait envoyer l'e-mail directement à l’adresse e-mail du site.
  • Si la soumission concernait un problème de paiement lié à une boutique, il fallait envoyer l'e-mail à la boutique concernée... si tant est que l'adresse mail de la boutique soit renseignée.

J’ai donc créé un gestionnaire personnalisé que nous allons découvrir dans la suite de ce blog.

 

La création du Custom Module

La structure de dossier nécessaire est la suivante :

▾ modules/
▾ custom/
▾ my_module_webform/
▾ src/
▾ Plugin/
▾ WebformHandler/

Il nous faudra ensuite créer le plugin, en ajoutant le fichier dans le répertoire WebformHandler. Dans notre cas, je vais l'appeler CustomRecipientWebformHandler.php et son contenu sera :

<?php


namespace Drupal\my_module_webform\Plugin\WebformHandler;


use Drupal\Core\Form\FormStateInterface;
use Drupal\webform\Annotation\WebformHandler;
use Drupal\webform\Plugin\WebformHandler\EmailWebformHandler;
use Drupal\webform\WebformSubmissionInterface;

/**
* Emails a webform submission.
*
* @WebformHandler(
* id = "custom_store_email",
* label = @Translation("Email – recipient based on store"),
* category = @Translation("Notification"),
* description = @Translation("Sends a webform submission to a different email address."),
* cardinality = \Drupal\webform\Plugin\WebformHandlerInterface::CARDINALITY_UNLIMITED,
* results = \Drupal\webform\Plugin\WebformHandlerInterface::RESULTS_PROCESSED,
* )
*/
class CustomRecipientWebformHandler extends EmailWebformHandler {

public function buildConfigurationForm(array $form, FormStateInterface $form_state) {
$form = parent::buildConfigurationForm($form, $form_state);
$form['to']['#access'] = FALSE;
return $form;
}


/**
* Sends and logs a webform submission message.
*
* @param \Drupal\webform\WebformSubmissionInterface $webform_submission
* A webform submission.
* @param array $message
* An array of message parameters.
*/
public function sendMessage(WebformSubmissionInterface $webform_submission, array $message) {

$recipient = \Drupal::config('system.site')->get('mail');
$data = $webform_submission->getData();
$establishmentId = $data['etablissement_de_votre_facture'];

if (!empty($establishmentId)) {
$store = \Drupal::entityTypeManager()->getStorage('establishment')
->load($establishmentId);
$email = $store->get('email')->value;
if (!empty($email)) {
$recipient = $email;
}
}

$message['to_mail'] = $recipient;

parent::sendMessage($webform_submission, $message);
}


}

Attention, il faudra bien renseigner les annotations afin que Drupal reconnaisse bien votre surcharge de plugin.

Ce plugin personnalisé permet de traiter les soumissions de formulaire Webform et d'envoyer un e-mail à une adresse spécifiée, en fonction des données saisies dans le formulaire.

Le plugin hérite de la classe de gestionnaire d'e-mail de formulaire Webform par défaut (EmailWebformHandler), mais modifie la méthode sendMessage() pour permettre de déterminer l'adresse e-mail à laquelle le message sera envoyé, en fonction des données du formulaire. Il récupère l'adresse e-mail stockée dans la configuration système par défaut de Drupal, puis vérifie si des données ont été saisies pour l'ID de l'établissement dans le formulaire. Si un ID d'établissement est trouvé, le plugin récupère l'adresse e-mail de l'établissement correspondant à partir de l'entité de stockage et remplace l'adresse email de destination par celle-ci.

J'utilise également la méthode buildConfigurationForm() pour masquer le champ "destinataire" dans le formulaire de configuration du gestionnaire de formulaire, car l'adresse e-mail est déterminée dynamiquement à partir des données du formulaire plutôt que d'être saisie manuellement par l'utilisateur du site.

Une fois le module activé, nous retrouvons ce nouveau gestionnaire dans l’administration de nos webforms : onglet « paramêtres » → sous-onglet « Emails / Handlers » :

Capture d'écran d'une sélection de WebformHandler

Une fois trouvé, il suffit de le sélectionner en cliquant sur le lien « Add handler ».

Pour finir, il suffira ensuite de configurer la notification. Vous remarquerez que dans notre cas, le champ destinataire n’est pas disponible puisque nous lui avons coupé l’accès via le plugin custom.

Capture d'écran du back-office d'un formulaire

Bien sûr, ceci n’est qu’un exemple de ce que nous pouvons faire avec les Webform Handlers. Les possibilités sont évidemment bien plus vastes en fonction des besoins que l’on recherche. 😉

Des articles techniques sur Drupal,  ça vous intéresse ? Je vous en propose 2 : 

Crédit photo : scyther5

Image mise en avant pour l'article
Fabien Estrabaud
Développeur Web
Webinar
Drupal 10, qu'est-ce qui change concrètement ?
Voir le webinar !
Vous maitrisez la technologie Drupal et vous souhaitez participer à une aventure humaine ?
Adimeo recrute un Développeur Drupal Senior capable d’encadrer des projets et d’accompagner des développeurs juniors...
Voir notre offre d'emploi !
Pourquoi s'abonner à
notre newsletter ?
Pour recevoir tous les mois, un condensé de contenus utiles et pertinents pour votre transformation digitale !