Formulaires d'entités personnalisées dans le cadre de l'édition et l'enregistrement d'utilisateurs

Lorsque vous utilisez le CMS Drupal, vous pouvez obtenir de nombreux éléments nécessaires à la mise en œuvre du projet sans écrire même une seule ligne de code. Cependant, si vous souhaitez afficher, par exemple, un formulaire d'édition d'utilisateur d'une manière personnalisée, alors un tel composant doit faire l'objet de certains travaux de programmation. Dans cet article, je vais vous expliquer comment enregistrer et afficher des modes personnalisés pour afficher des formulaires d'entité dans Drupal, et comment cela peut être utile pour votre projet.

Dans la version 8, Drupal a introduit l'une des fonctionnalités importantes – à savoir les modes d'affichage de formulaire d'entité. En principe, pour chaque entité basée sur un champ, c'est-à-dire celles qui implémentent l'interface Drupal\Core\Entity\FieldableEntityInterface, vous pouvez configurer les champs sur un formulaire par défaut. Vous pouvez également ajouter un nouveau mode d'affichage de formulaire et l'activer sur l'entité sélectionnée directement dans le panneau d'administration.

Dans l'exemple présenté, j'utiliserai le nouveau thème d'administration expérimental Claro.

Configuration initiale dans l'interface utilisateur

Chaque entité (telles que les entités intégrées – nœud, taxonomie, utilisateur) dispose d'un mécanisme intégré de gestion d'affichage de formulaire. Dans le cas des entités de type utilisateur, vous pouvez accéder à un tel formulaire à l'adresse suivante :

/admin/config/people/accounts/form-display

En plus du mode d'affichage par défaut, vous pouvez utiliser des modes d'affichage personnalisés en activant les modes sélectionnés dans la section inférieure :

Si votre liste est vide, cela signifie que vous n'avez pas encore enregistré de mode personnalisé pour votre entité dans le CMS. Vous pouvez le faire en accédant au formulaire sous :

/admin/structure/display-modes/form/add

Ensuite, vous cliquez sur le nom de l'entité choisie. Ce sera un utilisateur dans notre cas :

   
Dans le formulaire suivant, vous ne fournissez que l'étiquette et le nom machine.

Enregistrement du mode formulaire

Par défaut, dans Drupal, vous ne pouvez pas facilement afficher un formulaire d'entité après qu'il a été créé et déverrouillé dans l'interface utilisateur. Nous devons explicitement "dire" à votre entité quelle classe sera responsable de la gestion de l'affichage de votre formulaire. Il y a deux hooks à utiliser : hook_entity_type_build et hook_entity_type_alter.

Un exemple d'implémentation de hook pour une entité utilisateur pourrait donc ressembler à ceci :

/**
 * Implements hook_entity_type_build().
 */
function my_module_entity_type_build(array &$entity_types) {
  $form_modes = ['custom_form_mode_1', 'custom_form_mode_2'];

  foreach ($form_modes as $mode) {
    $entity_types['user']->setFormClass($mode, 'Drupal\user\ProfileForm');
  }
}

La plupart des entités intégrées ont déjà des classes pour gérer les formulaires, et nous pouvons les utiliser avec succès. Il est important que notre classe étende la classe :

namespace Drupal\Core\Entity\ContentEntityForm;

Page propre avec un formulaire

Afin d'afficher un formulaire d'entité personnalisé en tant que page indépendante avec un formulaire, vous pouvez utiliser l'option de créer votre propre routage qui gérera automatiquement son chargement. Il est primordial de définir la valeur _entity_form dans sa configuration, grâce à laquelle la classe appropriée responsable de la génération de la structure du formulaire sera trouvée.
Une exemple de configuration de routage pour une page de formulaire utilisateur pourrait ressembler à ceci :

my_custom_module.user.edit_form:
 path: '/user/{user}/custom-form-mode-1'
 defaults:
   _entity_form: user.custom_form_mode_1
   _title: 'Mode de formulaire personnalisé de l'entité utilisateur 1'
 requirements:
   _permission: 'la permission requise va ici'

Il n'est pas nécessaire de déclarer un contrôleur supplémentaire ou un formulaire séparé.

Chargement du formulaire de manière indépendante

Afficher un formulaire d'entité sur une page séparée ne répond souvent pas aux attentes en matière de design. Il est donc nécessaire d'avoir des mécanismes pour le charger dans d'autres cas, par exemple comme contenu de bloc ou comme élément de modèle intégré ou personnalisé. Dans le cas des entités utilisateurs, il peut s'agir d'un simple formulaire pour éditer l'avatar ou les données du profil à afficher, par exemple dans un bloc.

Pour atteindre l'objectif ici, il est nécessaire de réaliser plusieurs étapes, qui effectueront des opérations similaires à celles qui sont implicitement effectuées lors de l'affichage de votre propre page sur la base du routage, mais dans un sens beaucoup plus général.

Pour commencer, vous aurez besoin de l'un des services les plus fréquemment utilisés pour gérer les types d'entités :

$entityTypeManager = \Drupal::entityTypeManager();

Bien sûr, je recommande d'injecter le service si l'implémentation est dans le corps de classe.
Ce manager est capable de vous montrer la classe appropriée responsable de l'affichage du formulaire implémentant \Drupal\Core\Entity\EntityFormInterface en fournissant le paramètre id du type d'entité et le mode formulaire.

$entity_type_id = 'user';
$form_mode = 'my_custom_form_mode_2';
$userForm = $entityTypeManager->getEntityForm($entity_type_id, $form_mode);

Ensuite, vous devez informer votre formulaire d'entité sur quelle instance spécifique de ce type d'entité vous allez travailler. Nous pouvons à la fois charger une entité existante et en créer une nouvelle :

$existingUser = $entityTypeManager->getStorage('user')->load($user_id);
// ou
$newUser = $entityTypeManager->getStorage('user')->create();

et ensuite la définir comme une entité de formulaire :

$userForm->setEntity($existingUser);
// ou
$userForm->setEntity($newUser);

Avec un objet formulaire d'entité préparé de cette manière, vous pouvez finalement construire sur sa base la structure du formulaire final en utilisant le service \Drupal::formBuilder().

$form = \Drupal::formBuilder()->getForm($userForm);

Un tel formulaire est un tableau qui peut être directement rendu n'importe où dans votre code, conformément à la documentation de la méthode getForm de l'interface Drupal\Core\Form\FormBuilderInterface.

Modules utiles

Malheureusement, dans l'écosystème Drupal, il n'existe pas de nombreux modules qui facilitent la résolution du problème que nous examinons. L'un de ceux-ci est le module Entityform block, qui permet d'afficher le formulaire d'une entité sélectionnée dans un bloc. Un autre module qui ne résout le problème que de manière indirecte est le Inline Entity Form, qui fournit un widget permettant d'afficher un champ avec une référence d'entité sous forme de formulaire d'entité. Il convient également de mentionner le module Paragraphs, qui fournit également un widget pour afficher le formulaire d'un champ avec une référence à l'entité paragraphe.

Résumé

Les formulaires d'entité personnalisés sont une fonctionnalité très pratique mais nécessitent encore un certain travail de développeur Drupal. Heureusement, il s'avère que de nombreux mécanismes prêts à l'emploi nous permettent d'obtenir l'effet souhaité avec une configuration rapide du fichier .yml ou quelques lignes de code. La mise en œuvre d'un tel formulaire sur une page dédiée ou sous forme de bloc propre ne devrait donc pas poser de problèmes majeurs. Alors, bonne chance !