Création d’un composant de formulaire personnalisé dans un bloc de formulaire adaptatif

Edge Delivery Services pour AEM Forms offre des possibilités de personnalisation, ce qui permet aux développeurs et développeuses front-end de créer des composants de formulaire personnalisés. Ces composants personnalisés s’intègrent de manière transparente à l’expérience de création WYSIWYG, ce qui permet aux créateurs et créatrices de formulaires de les ajouter, de les configurer et de les gérer facilement dans l’éditeur de formulaires. Grâce aux composants personnalisés, les créateurs et créatrices peuvent améliorer leurs fonctionnalités tout en assurant un processus de création fluide et intuitif.

Ce document décrit les étapes à suivre pour créer des composants personnalisés en mettant en forme les composants de formulaire HTML natifs afin d’améliorer l’expérience client et l’attrait visuel du formulaire.

Aperçu de l’architecture

Le composant personnalisé du bloc Forms suit un modèle d’architecture MVC (Model-View-Controller)  :

Modèle

Mode

Logique de contrôleur/composant

Composants prêts à l’emploi

Les composants prêts à l’emploi (OOTB) constituent la base du développement personnalisé :

L’extension d’un composant prêt à l’emploi existant vous permet de réutiliser sa structure de base, son comportement et ses propriétés tout en le personnalisant en fonction de vos besoins.

Structure du composant personnalisé

Pour créer des composants personnalisés, vous pouvez utiliser l’interface de ligne de commande Scaffolder afin de configurer les fichiers et les dossiers requis pour votre composant, puis d’ajouter du code pour votre composant personnalisé.

Réutilisation et extension de champs dans des composants personnalisés

Lors de la définition de champs dans le fichier JSON de votre composant personnalisé (pour n’importe quel groupe de champs, de base, de validation, d’aide, etc.), suivez ces bonnes pratiques en matière de maintenabilité et de cohérence :

Définition de nouvelles propriétés pour les composants personnalisés

API JavaScript de composant personnalisé

L’API JavaScript de composant personnalisé définit comment contrôler le comportement, l’apparence et la réactivité de votre composant de formulaire personnalisé.

Fonction de décoration

La fonction de decoration est le point d’entrée de votre composant personnalisé. Elle initialise le composant, le lie à sa définition JSON et vous permet de manipuler sa structure et son comportement HTML.

Signature de fonction :

export default function decorate(element, fieldJson, container, formId)
{
  // element: The HTML structure of the OOTB component you are extending
  // fieldJson: The JSON field definition (all authorable properties)
  // container: The parent element (fieldset or form)
  // formId: The id of the form

  // ... your logic here ...
}

Elle peut :

Fonction d’abonnement

La fonction d’abonnement permet à votre composant de réagir aux modifications des valeurs de champ ou des événements personnalisés. Cela garantit que le composant reste synchronisé avec le modèle de données du formulaire et peut mettre à jour dynamiquement son interface d’utilisation.

Signature de fonction :

import { subscribe } from '../../rules/index.js';
export default function decorate(fieldDiv, fieldJson, container, formId) {
  // Access custom properties defined in the JSON
  const { initialText, finalText, time } = fieldJson?.properties;

  // ... setup logic ...

  subscribe(fieldDiv, formId, (_fieldDiv, fieldModel) => {
    fieldModel.subscribe(() => {
      // React to custom event (e.g., resetCardOption)
      // ... logic ...
    }, 'resetCardOption');
  });
}

Elle peut :

Créer un composant personnalisé

Dans cette section, vous découvrirez le processus de création d’un composant personnalisé de cartes en étendant le composant de case d’option prêt à l’emploi.

​1. Configuration du code

1.1 Fichiers et dossiers

La première étape consiste à configurer les fichiers nécessaires du composant personnalisé et à le relier au code dans le référentiel. Ce processus est effectué automatiquement par l’interface de ligne de commande d’AEM Forms Scaffolder, ce qui permet de structurer et de relier les fichiers nécessaires.

npm install
npm run create:custom-component

Il pourra:

Cela crée tous les dossiers et fichiers nécessaires, notamment :

blocks/form/
└── components/
  └── cards/
    ├── cards.js
    └── cards.css
    └── _cards.json

Cela les relie également avec le reste du code du référentiel, comme indiqué dans la sortie de l’interface de ligne de commande.
Cela exécute automatiquement les fonctionnalités ci-dessous :

1.2 Utilisation du composant dans l’éditeur universel

Comme aucun code n’est présent dans cards.js, le composant personnalisé est rendu en tant que groupe de cases d’option.

1.3 Prévisualiser et tester localement

Maintenant que le formulaire contient le composant personnalisé, vous pouvez créer une version proxy du formulaire et y apporter des modifications localement pour voir les modifications :

2. Mise en œuvre du comportement personnalisé de votre composant personnalisé

2.1 Style du composant personnalisé

Ajoutons une classe card au composant pour le style et ajoutez une image pour chaque case d’option. Utilisez le code ci-dessous pour cela.

Mettre en forme le composant à l’aide de card.js

import { createOptimizedPicture } from '../../../../scripts/aem.js';

export default function decorate(element, fieldJson, container, formId) {
  element.classList.add('card');

  element.querySelectorAll('.radio-wrapper').forEach((radioWrapper) => {
    const image = createOptimizedPicture(
      'https://main--afb--jalagari.hlx.live/lab/images/card.png',
      'card-image'
    );
    radioWrapper.appendChild(image);
  });

  return element;
}

Ajouter un comportement d’exécution à l’aide de cards.css

.card .radio-wrapper {
  min-width: 320px; /* or whatever width fits your design */
  max-width: 340px;
  background: #fff;
  border-radius: 16px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
  flex: 0 0 auto;
  scroll-snap-align: start;
  padding: 24px 16px;
  margin-bottom: 0;
  position: relative;
  transition: box-shadow 0.2s;
  display: flex;
  align-items: flex-start;
  gap: 12px;
}

Désormais, le composant Cartes se présente comme suit :

2.2 Ajout d’un comportement dynamique à l’aide de la fonction d’abonnement

Lorsque la liste déroulante est modifiée, les cartes sont récupérées et définies dans l’énumération du groupe de cases d’option. Mais actuellement, la vue ne gère pas cela. Le rendu est donc effectué comme illustré ci-dessous :

Lorsque l’API est appelée, elle définit le modèle de champ et doit écouter les modifications et effectuer le rendu de la vue en conséquence. Pour ce faire, utilisez la fonction d’abonnement.

Convertissons le code d’affichage de l’étape précédente en une fonction et appelons-le dans la fonction d’abonnement dans cards.js comme illustré ci-dessous :

import { createOptimizedPicture } from '../../../../scripts/aem.js';
import { subscribe } from '../../rules/index.js';

function createCard(element, enums) {
  element.querySelectorAll('.radio-wrapper').forEach((radioWrapper, index) => {
    if (enums[index]?.name) {
      let label = radioWrapper.querySelector('label');

      if (!label) {
        label = document.createElement('label');
        radioWrapper.appendChild(label);
      }

      label.textContent = enums[index]?.name;
    }

    const image = createOptimizedPicture(
      enums[index]?.image || 'https://main--afb--jalagari.hlx.page/lab/images/card.png',
      'card-image'
    );

    radioWrapper.appendChild(image);
  });
}

export default function decorate(element, fieldJson, container, formId) {
  element.classList.add('card');
  createCard(element, fieldJson.enum);

  subscribe(element, formId, (fieldDiv, fieldModel) => {
    fieldModel.subscribe((e) => {
      const { payload } = e;

      payload?.changes?.forEach((change) => {
        if (change?.propertyName === 'enum') {
          createCard(element, change.currentValue);
        }
      });
    });
  });

  return element;
}

Utiliser la fonction d’abonnement pour écouter les modifications d’événement dans cards.js

Désormais, lorsque vous modifiez la liste déroulante, les cartes sont renseignées comme illustré ci-dessous :

2.3 Synchronisation des mises à jour des affichages avec le modèle de champ

Pour synchroniser les modifications de l’affichage avec le modèle de champ, vous devez définir la valeur de la carte sélectionnée. Ajoutez donc l’écouteur d’événement de modification suivant dans cards.js, comme illustré ci-dessous :

Utilisation de l’API de modèle de champ dans cards.js

import { createOptimizedPicture } from '../../../../scripts/aem.js';
import { subscribe } from '../../rules/index.js';

function createCard(element, enums) {
  element.querySelectorAll('.radio-wrapper').forEach((radioWrapper, index) => {
    if (enums[index]?.name) {
      let label = radioWrapper.querySelector('label');

      if (!label) {
        label = document.createElement('label');
        radioWrapper.appendChild(label);
      }

      label.textContent = enums[index]?.name;
    }

    // Attach index to input element for later reference
    radioWrapper.querySelector('input').dataset.index = index;

    const image = createOptimizedPicture(
      enums[index]?.image || 'https://main--afb--jalagari.hlx.page/lab/images/card.png',
      'card-image'
    );

    radioWrapper.appendChild(image);
  });
}

export default function decorate(element, fieldJson, container, formId) {
  element.classList.add('card');
  createCard(element, fieldJson.enum);

  subscribe(element, formId, (fieldDiv, fieldModel) => {
    fieldModel.subscribe((e) => {
      const { payload } = e;

      payload?.changes?.forEach((change) => {
        if (change?.propertyName === 'enum') {
          createCard(element, change.currentValue);
        }
      });
    });

    element.addEventListener('change', (e) => {
      e.stopPropagation();
      const value = fieldModel.enum?.[parseInt(e.target.dataset.index, 10)];
      fieldModel.value = value.name;
    });
  });

  return element;
}

Le composant de carte personnalisée s’affiche désormais, comme illustré ci-dessous :

3. Valider et envoyer les modifications

Une fois que vous avez implémenté le code JavaScript et CSS de votre composant personnalisé et que vous l’avez vérifié localement, validez et envoyez les modifications à votre référentiel Git.

git add . && git commit -m "Add card custom component" && git push

Vous avez créé un composant de sélection de carte personnalisée complexe en quelques étapes simples.

Créer un composant composite

Un composant composite est créé en combinant plusieurs composants.
Par exemple, un composant composite de conditions générales est constitué d’un panneau parent qui contient les éléments suivants :

Cette structure de composition est définie comme modèle à l’intérieur du fichier JSON du composant correspondant. L’exemple suivant montre comment définir un modèle pour un composant Conditions générales :

{
  "definitions": [
    {
      "title": "Terms and conditions",
      "id": "tnc",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/fd/components/form/termsandconditions/v1/termsandconditions",
            "template": {
              "jcr:title": "Terms and conditions",
              "fieldType": "panel",
              "fd:viewType": "tnc",
              "text": {
                "value": "Text related to the terms and conditions come here.",
                "sling:resourceType": "core/fd/components/form/text/v1/text",
                "fieldType": "plain-text",
                "textIsRich": true
              },
              "approvalcheckbox": {
                "name": "approvalcheckbox",
                "jcr:title": "I agree to the terms & conditions.",
                "sling:resourceType": "core/fd/components/form/checkbox/v1/checkbox",
                "fieldType": "checkbox",
                "required": true,
                "type": "string",
                "enum": [
                  "true"
                ]
              }
            }
          }
        }
      }
    }
  ],
  ...
}

Bonnes pratiques

Gardez les points suivants à l’esprit avant de créer votre propre composant personnalisé :

Références