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 d’usine

Les composants prêts à l’emploi OOTB) qui 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 CLI 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 decoration est le point d’entrée de votre composant personnalisé. Il 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 ...
}

Il peut :

Fonction d'abonnement

La fonction subscribe 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 utilisateur.

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');
  });
}

Il peut :

Création d’un composant personnalisé

Dans cette section, vous découvrirez le processus de création d’un composant personnalisé cartes de visite en étendant le composant de bouton radio 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 connecter 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 accélère la génération de modèles et le câblage des fichiers nécessaires.

npm install
npm run create:custom-component

Il permettra :

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

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

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

1.2 Utilisation du composant dans l’éditeur universel

Comme aucun code n’est présent à l’intérieur 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 remplacer le 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 radio. 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. Il effectue donc le rendu 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 subscribe.

Convertissons le code d’affichage de l’étape précédente en une fonction et appelons-le dans la fonction subscribe 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;
}

Utilisez la fonction Subscribe pour écouter les changements 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 vues avec le modèle de champ

Pour synchroniser les modifications de la vue 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 maintenant, comme illustré ci-dessous :

​3. Valider et envoyer les modifications

Une fois que vous avez implémenté le JavaScript et le CSS de votre composant personnalisé et que vous l’avez vérifié localement, validez et transmettez 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éation d’un composant composite

Un composant composite est créé en combinant plusieurs composants.
Par exemple, un composant composite de conditions générales se compose 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 Termes et conditions :

{
  "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