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 Forms-Block folgt einem MVC (Model View Controller-Architekturmuster:

Modell

Anzeigen

Controller-/Komponentenlogik

Vorkonfigurierte Komponenten

OOTB-Komponenten (Out-of-the-Box 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, um die für Ihre Komponente erforderlichen Dateien und Ordner einzurichten und dann Code für Ihre benutzerdefinierte Komponente hinzuzufü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

Benutzerdefinierte JavaScript-API-Komponente

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

Funktion dekorieren

Die Funktion dekorieren 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 ...
}

Er kann:

Subscribe-Funktion

Die subscribe-Funktion ermöglicht es Ihrer Komponente, auf Änderungen von Feldwerten oder benutzerdefinierte 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');
});
}

Er kann:

Erstellen einer benutzerdefinierten Komponente

In diesem Abschnitt erfahren Sie, wie Sie eine benutzerdefinierte Kartenkomponente erstellen indem Sie vordefinierte Optionsschaltflächen-Komponente 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 Verkabelung der erforderlichen Dateien beschleunigt wird.

npm install
npm run create:custom-component

Sie wird:

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

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

Und verkabelt ihn mit dem Rest des Codes im Repository, wie in der Ausgabe der CLI gezeigt.
Er führt die folgenden Funktionen automatisch aus:

1.2 Verwenden der Komponente im universellen Editor

Da innerhalb von kein Code vorhanden ist, cards.js die 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, um die Änderungen zu sehen:

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

2.1 Gestalten der benutzerdefinierten Komponente

Fügen wir der Komponente für Formatierung eine Klasse () hinzu und fügen Sie für jedes Optionsfeld ein Bild hinzu. Verwenden Sie dazu den folgenden Code.

Gestalten Sie die benutzerdefinierte Komponente mithilfe der Decorate-Funktion in cards.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 für die benutzerdefinierte Komponente in 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 Dynamisches Verhalten mithilfe der Anmeldefunktion hinzufügen

Wenn das Dropdown-Menü geändert wird, werden die Karten abgerufen und in der Aufzählung der Optionsfeldgruppe festgelegt. Aber die Ansicht verarbeitet dies derzeit nicht. Daher wird wie unten gezeigt gerendert:

Beim Aufruf der API wird das Feldmodell festgelegt, die Änderungen müssen überwacht und die Ansicht entsprechend gerendert werden. Dies wird mithilfe der "".

Konvertieren wir den Ansichtscode im vorherigen Schritt in eine Funktion und rufen Sie dies in der Funktion zum Abonnieren in cards.js auf, wie unten dargestellt:

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 Sie die Funktion „Abonnieren“, um die Ereignisänderungen in cards.js zu überwachen

Wenn Sie jetzt das Dropdown-Menü ändern, werden die Karten wie unten dargestellt gefü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 hinzu, wie unten gezeigt:

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;

    }

    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:

Änderungen übertragen und per Push übertragen

Nachdem Sie JavaScript und CSS für Ihre benutzerdefinierte Komponente implementiert und lokal überprüft haben, übertragen 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.

Manuelle oder veraltete Methode zum Erstellen benutzerdefinierter Komponenten

Die Legacy-Methode dazu besteht darin, die unten beschriebenen Schritte manuell auszuführen:

Jetzt können Sie die benutzerdefinierte Komponente zu Ihrem Formular hinzufügen.

Erstellen einer zusammengesetzten Komponente

Eine zusammengesetzte Komponente wird durch Kombinieren mehrerer Komponenten erstellt.
Eine zusammengesetzte Komponente der Nutzungsbedingungen besteht beispielsweise aus einem übergeordneten Bedienfeld, 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 der 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