Aangepaste formuliercomponent maken in adaptief formulierblok

Edge Delivery Services Forms biedt aanpassing, waardoor ontwikkelaars aan de voorzijde op maat aangepaste formulieronderdelen kunnen maken. Deze aangepaste componenten worden naadloos geïntegreerd in de WYSIWYG-ontwerpervaring, zodat formulierauteurs ze eenvoudig kunnen toevoegen, configureren en beheren in de formuliereditor. Met aangepaste componenten kunnen auteurs de functionaliteit verbeteren en tegelijkertijd zorgen voor een vloeiend en intuïtief ontwerpproces.

In dit document worden de stappen beschreven waarmee u aangepaste componenten kunt maken door de native HTML-formuliercomponenten op te maken om de gebruikerservaring te verbeteren en de visuele aantrekkingskracht van het formulier te vergroten.

Overzicht van architectuur

De component van de douane voor het Blok van Forms volgt een MVC (model-mening-Controlemechanisme) architectuurpatroon:

Model

Weergave

Controller/Component Logic

OOTB-componenten

OOTB (uit-van-de-doos) componenten verstrekken de stichting voor douaneontwikkeling:

Door een bestaande OOTB-component uit te breiden, kunt u de basisstructuur, het gedrag en de eigenschappen ervan opnieuw gebruiken en deze aan uw wensen aanpassen.

Structuur van aangepaste component

Om douanecomponenten tot stand te brengen, kunt u folder CLI gebruiken aan opstelling de dossiers en de omslagen die voor uw component worden vereist en dan code voor uw douanecomponent toevoegen.

Velden in aangepaste componenten opnieuw gebruiken en uitbreiden

Volg bij het definiëren van velden in JSON van uw aangepaste component (voor elke veldgroep, basis, validatie, Help, enzovoort) de onderstaande tips en trucs voor onderhoudsgemak en consistentie:

Nieuwe eigenschappen definiëren voor aangepaste componenten

Aangepaste JavaScript-API voor componenten

De API van de Component van de Douane bepaalt hoe te om het gedrag, de verschijning, en de reactiviteit van uw douaneformuliercomponent te controleren.

Decoratiefunctie

decoreert functie is het ingangspunt voor uw douanecomponent. De component wordt geïnitialiseerd, gekoppeld aan de JSON-definitie en u kunt de HTML-structuur en -gedrag van de component bewerken.

Functiehandtekening:

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

Het kan:

Functie Abonneren

De subscribe functie laat uw component toe om op veranderingen in gebiedswaarden of douanegebeurtenissen te reageren. Hierdoor blijft de component synchroon met het gegevensmodel van het formulier en kan de gebruikersinterface van het formulier dynamisch worden bijgewerkt.

Functiehandtekening:

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

Het kan:

Een aangepaste component maken

In deze sectie, zult u het proces leren om de component van de a kaartendouane tot stand te brengen door OOTB radioknoopcomponent uit te breiden.

​1. Code-instelling

1.1 Bestanden en mappen

De eerste stap is de opstelling van de noodzakelijke dossiers van de douanecomponent en het te telegraferen tot de code in de bewaarplaats. Dit proces wordt automatisch gedaan door AEM Forms Scaffolder CLI, die het sneller maakt om de noodzakelijke dossiers te scaffold en te telegraferen.

npm install
npm run create:custom-component

Het zal:

Hiermee maakt u alle benodigde mappen en bestanden, waaronder:

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

En draai het omhoog met de rest code in de bewaarplaats zoals aangetoond in de output van CLI.
De volgende functies worden automatisch uitgevoerd:

1.2 Component gebruiken in Universal Editor

Aangezien er geen code aanwezig is binnen cards.js , wordt de aangepaste component weergegeven als een groep keuzerondjes.

1.3 Lokaal voorvertonen en testen

Nu het formulier de aangepaste component bevat, kunt u het formulier als proxy instellen en er lokaal wijzigingen in aanbrengen. De wijzigingen worden dan weergegeven:

​2. Aangepast gedrag voor uw aangepaste component implementeren

2.1 De aangepaste component opmaken

Laat een klasse kaart aan de component voor het stileren toevoegen en een beeld voor elke radio toevoegen, gebruik de hieronder code voor dit.

Stijl de component gebruikend 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;
}

voeg Runtime Gedrag toe gebruikend 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;
}

De kaartcomponent ziet er nu als volgt uit:

toe

2.2 Dynamisch gedrag toevoegen met behulp van Abonnementsfunctie

Wanneer de vervolgkeuzelijst wordt gewijzigd, worden de kaarten opgehaald en ingesteld in de opsomming van de groep keuzerondjes. Maar dit wordt momenteel niet in de weergave verwerkt. Het wordt dus weergegeven zoals hieronder wordt getoond:

Wanneer API wordt geroepen, plaatst het het gebiedsmodel en moet aan de veranderingen luisteren en dienovereenkomstig de mening teruggeven. Dit wordt bereikt gebruikend onderteken functie.

Laten we de weergavecode in de vorige stap omzetten naar een functie en deze binnen de subscribe-functie in cards.js aanroepen, zoals hieronder wordt getoond:

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

Gebruik onderteken Functie om de Veranderingen van de Gebeurtenis in cards.js te luisteren

Wanneer u het vervolgkeuzemenu wijzigt, worden de kaarten gevuld, zoals hieronder wordt weergegeven:

2.3 Updates synchroniseren met veldmodel

Als u de weergavewijzigingen wilt synchroniseren met het veldmodel, moet u de waarde van de geselecteerde kaart instellen. Voeg dus de volgende gebeurtenislistener voor een wijziging toe aan cards.js, zoals hieronder wordt weergegeven:

Gebruikend het ModelAPI van het Gebied 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;
}

De aangepaste kaartcomponent wordt nu weergegeven, zoals hieronder wordt getoond:

​3. Wijzigingen vastleggen en duwen

Nadat u de JavaScript en CSS voor uw aangepaste component hebt geïmplementeerd en lokaal hebt geverifieerd, past u de wijzigingen toe op uw Git-opslagplaats en drukt u deze door.

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

U hebt in een paar eenvoudige stappen een complexe component voor de selectie van een aangepaste kaart gemaakt.

Een samengestelde component maken

Een samengestelde component wordt gecreeerd door veelvoudige componenten te combineren.
Een samengestelde component Voorwaarden en Voorwaarden bestaat bijvoorbeeld uit een bovenliggend deelvenster dat het volgende bevat:

Deze compositiestructuur wordt gedefinieerd als een sjabloon binnen het JSON-bestand van de desbetreffende component. In het volgende voorbeeld wordt getoond hoe u een sjabloon voor een component Voorwaarden definieert:

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

Aanbevolen procedures

Houd rekening met de onderstaande punten voordat u uw eigen aangepaste component maakt:

Verwijzingen