Creazione del componente Modulo personalizzato nel blocco di moduli adattivi

I moduli di Edge Delivery Services offrono funzionalità di personalizzazione e permettono agli sviluppatori front-end di creare componenti per moduli su misura. Questi componenti personalizzati si integrano direttamente nell’esperienza di authoring WYSIWYG, consentendo agli autori di moduli di aggiungerli, configurarli e gestirli facilmente nell’editor di moduli. I componenti personalizzati permettono agli autori di ottimizzare le funzionalità dei moduli. Inoltre, assicurano un processo di authoring fluido e intuitivo.

Questo documento illustra i passaggi necessari per creare componenti personalizzati assegnando uno stile ai componenti per moduli HTML nativi, migliorando l’esperienza utente e aumentando l’impatto visivo dei moduli stessi.

Panoramica dell’architettura

Il componente personalizzato per il blocco moduli segue un pattern di architettura MVC (Model-View-Controller):

Modello

Visualizzazione

Logica controller/componente

Componenti integrati

I componenti integrati forniscono le basi per lo sviluppo personalizzato:

L’estensione di un componente integrato esistente consente di riutilizzarne la struttura di base, il comportamento e le proprietà, nonché personalizzarlo in base alle esigenze.

Struttura del componente personalizzato

Per creare componenti personalizzati, puoi utilizzare CLI Scaffolder per configurare i file e le cartelle richiesti per il componente e quindi aggiungere il codice per il componente personalizzato.

Riutilizzo ed estensione dei campi nei componenti personalizzati

Quando definisci i campi nel JSON del componente personalizzato (per qualsiasi gruppo di campi, base, convalida, guida, ecc.), segui le best practice per manutenibilità e coerenza:

Definizione di nuove proprietà per i componenti personalizzati

API JavaScript del componente personalizzato

L’API JavaScript del componente personalizzato definisce come controllare il comportamento, l’aspetto e la reattività del componente del modulo personalizzato.

Funzione Decora

La funzione decora è il punto di ingresso del componente personalizzato. Inizializza il componente, lo collega alla sua definizione JSON e consente di manipolarne la struttura HTML e il comportamento.

Funzione Firma:

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

Può:

Funzione Abbonati

La funzione abbonati consente al componente di reagire alle modifiche nei valori dei campi o agli eventi personalizzati. In questo modo il componente rimane sincronizzato con il modello dati del modulo e può aggiornare dinamicamente la relativa interfaccia utente.

Funzione Firma:

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

Può:

Creazione di un componente personalizzato

In questa sezione imparerai il processo di creazione di un componente personalizzato schede estendendo il componente pulsante di scelta integrato.

​1. Configurazione del codice

1.1 File e cartelle

Il primo passaggio consiste nel configurare i file necessari del componente personalizzato e collegarlo al codice nell’archivio. Questo processo viene eseguito automaticamente dal CLI di AEM Forms Scaffolder, rendendo più rapido lo scaffolding e il collegamento dei file necessari.

npm install
npm run create:custom-component

Questo:

In questo modo vengono creati tutti i file e le cartelle necessari, tra cui:

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

E lo collega con il resto del codice nell’archivio come mostrato nell’output della CLI.
Esegue automaticamente le seguenti funzionalità:

1.2 Utilizzo del componente nell’editor universale

Poiché non è presente alcun codice all’interno di cards.js, il componente personalizzato viene riprodotto come gruppo di pulsanti di scelta.

1.3 Anteprima e test in locale

Ora che il modulo contiene il componente personalizzato, puoi eseguire il proxy del modulo, apportarvi modifiche in locale e visualizzarle:

​2. Implementazione del comportamento personalizzato per il componente personalizzato

2.1 Attribuzione dello stile al componente personalizzato

Aggiungiamo una scheda di classe al componente per l’attribuzione dello stile e un’immagine per ogni pulsante di scelta. A tale scopo, utilizza il codice seguente.

Personalizza lo stile del componente utilizzando 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;
}

Aggiungi comportamento runtime utilizzando 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;
}

Ora, il componente schede viene visualizzato come segue:

2.2 Aggiungere un comportamento dinamico tramite la funzione Abbonati

Quando il menu a discesa viene modificato, le schede vengono recuperate e impostate nell’enum del gruppo di pulsanti di scelta. Ma attualmente la visualizzazione non gestisce questa situazione. Viene quindi eseguito il rendering come mostrato di seguito:

Quando viene chiamata l’API, imposta il campo Modello e deve rilevare le modifiche ed eseguire di conseguenza il rendering della vista. Questa azione viene eseguita utilizzando la funzione abbonati.

Convertiamo il codice di visualizzazione del passaggio precedente in una funzione e chiamiamolo all’interno della funzione abbonati in cards.js come illustrato di seguito:

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

Utilizzare la funzione abbonati per rilevare le modifiche all’evento in cards.js

Ora, quando cambi il menu a discesa, le schede si popolano come mostrato di seguito:

2.3 Sincronizzazione degli aggiornamenti delle visualizzazioni con il modello di campo

Per sincronizzare le modifiche della visualizzazione al modello di campo, è necessario impostare il valore della scheda selezionata. Quindi, aggiungi il seguente listener di eventi di modifica in cards.js come mostrato di seguito:

Utilizzo dell’API modello di campo 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;
}

Ora mostra il componente scheda personalizzato, come illustrato di seguito:

​3. Confermare e inviare modifiche

Dopo aver implementato JavaScript e CSS per il componente personalizzato e averlo verificato in locale, conferma e invia le modifiche all’archivio Git.

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

Hai creato correttamente un componente complesso e personalizzato di selezione della scheda in pochi semplici passaggi.

Creare un componente personalizzato

Un componente composito viene creato combinando più componenti.
Ad esempio, un componente composito di Termini e condizioni è costituito da un pannello principale che contiene:

Questa struttura di composizione è definita come un modello all’interno del file JSON del rispettivo componente. L’esempio seguente mostra come definire un modello per un componente Termini e condizioni:

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

Tieni presente quanto segue prima di creare un componente personalizzato:

Riferimenti