Erstellen einer benutzerdefinierten Formularkomponente im adaptiven Formularblock

Edge Delivery Services Forms bietet eine Anpassung, die es Frontend-Entwicklerinnen und -Entwicklern ermöglicht, maßgeschneiderte Formularkomponenten zu erstellen. Diese benutzerdefinierten Komponenten lassen sich nahtlos in das WYSIWYG-Authoring-Erlebnis integrieren und können im Formulareditor einfach hinzugefügt, konfiguriert und verwaltet werden. Mit benutzerdefinierten Komponenten können Sie die Funktionalität verbessern und gleichzeitig einen reibungslosen und intuitiven Authoring-Prozess sicherstellen.

In diesem Dokument werden die Schritte zum Erstellen benutzerdefinierter Komponenten durch Formatieren der nativen HTML-Formularkomponenten beschrieben, um das Anwendererlebnis zu verbessern und den visuellen Reiz des Formulars zu erhöhen.

Architekturüberblick

Die benutzerdefinierte Komponente für den Formularblock folgt einem Architekturmuster des Typs MVC (Model-View-Controller):

Modell

Anzeigen

Controller-/Komponentenlogik

Vorkonfigurierte Komponenten

Vorkonfigurierte Komponenten bieten die Grundlage für die benutzerdefinierte Entwicklung:

Durch das Erweitern einer vorhandenen vorkonfigurierten Komponente können Sie deren Grundstruktur, Verhalten und Eigenschaften wiederverwenden und sie an Ihre Anforderungen anpassen.

Struktur der benutzerdefinierten Komponente

Um benutzerdefinierte Komponenten zu erstellen, können Sie die Strukturvorlagen-CLI verwenden und so die für Ihre Komponente erforderlichen Dateien und Ordner einrichten und dann Code für Ihre benutzerdefinierte Komponente hinzufügen.

Wiederverwenden und Erweitern von Feldern in benutzerdefinierten Komponenten

Befolgen Sie beim Definieren von Feldern im JSON-Code Ihrer benutzerdefinierten Komponente (für beliebige Feldergruppen, Standard, Validierung, Hilfe usw.) die folgenden Best Practices, um die Wartung und Konsistenz zu gewährleisten:

Definieren neuer Eigenschaften für benutzerdefinierte Komponenten

JavaScript-API für benutzerdefinierte Komponenten

Die JavaScript-API für benutzerdefinierte Komponenten definiert, wie das Verhalten, das Erscheinungsbild und die Reaktivität Ihrer benutzerdefinierten Formularkomponente gesteuert werden.

Funktion „decorate“

Die Funktion decorate ist der Einstiegspunkt für Ihre benutzerdefinierte Komponente. Sie initialisiert die Komponente, verknüpft sie mit ihrer JSON-Definition und ermöglicht es Ihnen, ihre HTML-Struktur und ihr Verhalten zu bearbeiten.

Funktionssignatur:

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 ...
}

Sie kann:

Funktion „subscribe“

Die Funktion subscribe ermöglicht es Ihrer Komponente, auf Änderungen von Feldwerten oder benutzerspezifische Ereignisse zu reagieren. Dadurch wird sichergestellt, dass die Komponente mit dem Formulardatenmodell synchron bleibt und ihre Benutzeroberfläche dynamisch aktualisieren kann.

Funktionssignatur:

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

Sie kann:

Erstellen einer benutzerdefinierten Komponente

In diesem Abschnitt erfahren Sie, wie Sie eine benutzerdefinierte Kartenkomponente erstellen, indem Sie die vorkonfigurierte Optionsfeldkomponente erweitern.

1. Code-Einrichtung

1.1 Dateien und Ordner

Der erste Schritt besteht darin, die erforderlichen Dateien der benutzerdefinierten Komponente einzurichten und sie mit dem Code im Repository zu verbinden. Dieser Vorgang wird automatisch von der AEM Forms-Strukturvorlagen-CLI durchgeführt, wodurch die Strukturierung und Verbindung der erforderlichen Dateien beschleunigt wird.

npm install
npm run create:custom-component

Sie werden:

Dadurch werden alle erforderlichen Ordner und Dateien erstellt, einschließlich:

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

Außerdem wird alles mit dem Rest des Codes im Repository verbunden, wie in der Ausgabe der CLI gezeigt.
Die folgenden Funktionen werden automatisch ausgeführt:

1.2 Verwenden der Komponente im universellen Editor

Da innerhalb von cards.js kein Code vorhanden ist, wird benutzerdefinierte Komponente als Optionsfeldgruppe gerendert.

1.3 Lokale Vorschau und Tests

Da das Formular nun die benutzerdefinierte Komponente enthält, können Sie das Formular als Proxy verwenden und lokal Änderungen daran vornehmen und diese anzeigen:

2. Implementieren von benutzerdefiniertem Verhalten für Ihre benutzerdefinierte Komponente

2.1 Gestalten der benutzerdefinierten Komponente

Fügen Sie der Komponente zur Gestaltung die Klasse card und für jedes Optionsfeld ein Bild hinzu. Verwenden Sie dazu den folgenden Code.

Gestalten Sie die Komponente mit 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;
}

Laufzeitverhalten mithilfe von cards.css hinzufügen

.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;
}

Die Kartenkomponente sieht nun wie folgt aus:

2.2 Hinzufügen von dynamischem Verhalten mithilfe der Funktion „subscribe“

Wenn die Dropdown-Liste geändert wird, werden die Karten abgerufen und in der Aufzählung der Optionsfeldgruppe festgelegt. Die Ansicht kann dies jedoch derzeit nicht verarbeiten. Daher wird dies wie unten dargestellt gerendert:

Beim Aufruf der API wird das Feldmodell festgelegt. Die Änderungen müssen überwacht und die Ansicht entsprechend gerendert werden. Dies wird mithilfe der Funktion „subscribe“ erreicht.

Konvertieren Sie den Ansichts-Code im vorherigen Schritt in eine Funktion und rufen Sie dies wie unten dargestellt in der Funktion „subscribe“ in cards.js auf:

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

Verwenden der Funktion „subscribe“, um die Ereignisänderungen in „cards.js“ zu überwachen

Wenn Sie jetzt die Dropdown-Liste ändern, werden die Karten wie unten dargestellt befüllt:

2.3 Synchronisieren von Ansichtsaktualisierungen mit dem Feldmodell

Zum Synchronisieren der Ansichtsänderungen mit dem Feldmodell müssen Sie den Wert der ausgewählten Karte festlegen. Fügen Sie also den folgenden Änderungsereignis-Listener in „cards.js“ wie unten dargestellt hinzu:

Verwenden der Feldmodell-API in „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;
}

Jetzt wird die benutzerdefinierte Kartenkomponente angezeigt, wie unten dargestellt:

3. Committen und Übertragen von Änderungen

Nachdem Sie JavaScript und CSS für Ihre benutzerdefinierte Komponente implementiert und lokal überprüft haben, committen Sie die Änderungen in Ihr Git-Repository.

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

Sie haben in wenigen einfachen Schritten erfolgreich eine komplexe benutzerdefinierte Kartenauswahlkomponente erstellt.

Erstellen einer zusammengesetzten Komponente

Eine zusammengesetzte Komponente wird durch Kombinieren mehrerer Komponenten erstellt.
Eine zusammengesetzte Komponente des Typs „Nutzungsbedingungen“ besteht beispielsweise aus einem übergeordneten Panel, das Folgendes enthält:

Diese Kompositionsstruktur wird als Vorlage innerhalb der JSON-Datei der jeweiligen Komponente definiert. Das folgende Beispiel zeigt, wie Sie eine Vorlage für eine Komponente des Typs „Nutzungsbedingungen“ definieren:

{
  "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"
                ]
              }
            }
          }
        }
      }
    }
  ],
  ...
}

Best Practices

Beachten Sie die folgenden Punkte, bevor Sie Ihre eigene benutzerdefinierte Komponente erstellen:

Verweise