Sviluppare il blocco Edge Delivery Services

Il nostro obiettivo è generare un blocco dinamico di Edge Delivery Services che chiama una funzione Edge di AEM per recuperare dati dinamici da un’API di terze parti.

Il secondo passaggio consiste nello sviluppare il blocco Edge Delivery Services, che esegue lo scaffolding di un modello JSON, JavaScript e CSS e lo crea in Universal Editor. Per informazioni di base sulla sintassi del modello a blocchi e sulla struttura JavaScript e CSS, consulta Creare un blocco e Creare un blocco. Qui vengono trattate solo le parti specifiche di questa esercitazione.

Questo passaggio non chiama ancora la funzione Edge di AEM generata nel passaggio precedente. Il blocco Edge Delivery Services restituisce un risultato segnaposto fino a quando Connetti il blocco alla funzione AEM Edge effettua il wetch.

Creare un ramo

Nel progetto del sito Edge Delivery Services, crea un ramo per questa funzione.

$ git checkout -b estimated-delivery

Definire il modello di blocco

Prima di scrivere il JavaScript, definisci quali campi controlla un autore e quali campi il codice esegue il rendering autonomamente, in modo che il modello di contenuto rimanga piccolo.

Il modello in _estimated-delivery.json espone solo due campi, l’intestazione e l’etichetta del pulsante. L’elenco dei prodotti, il markup del modulo e gli stati dei risultati vengono riprodotti dal JavaScript del blocco Edge Delivery Services, non dai contenuti creati.

// blocks/estimated-delivery/_estimated-delivery.json
{
  "definitions": [
    {
      "title": "Estimated Delivery",
      "id": "estimated-delivery",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/franklin/components/block/v1/block",
            "template": {
              "name": "Estimated Delivery",
              "model": "estimated-delivery",
              "title": "When will it arrive?",
              "ctaText": "Check estimated delivery"
            }
          }
        }
      }
    }
  ],
  "models": [
    {
      "id": "estimated-delivery",
      "fields": [
        {
          "component": "text",
          "valueType": "string",
          "name": "title",
          "value": "When will it arrive?",
          "label": "Heading",
          "description": "Main heading shown above the delivery checker form."
        },
        {
          "component": "text",
          "valueType": "string",
          "name": "ctaText",
          "value": "Check estimated delivery",
          "label": "CTA Text",
          "description": "Label for the submit button."
        }
      ]
    }
  ],
  "filters": []
}

Per i tipi di campo oltre text, seguire la sintassi del modello in Creare un blocco.

Registra il blocco per l’editor universale

Il file del modello di blocco da solo non è sufficiente per consentire a Universal Editor di offrire il blocco nel selettore di inserimento. Per altri due file è necessaria innanzitutto una voce manuale, poiché elencano i blocchi per nome anziché individuarli automaticamente.

Aggiungere il blocco al gruppo “Blocchi” in models/_component-definition.json:

{ "...": "../blocks/estimated-delivery/_*.json#/definitions" }

Se il blocco deve essere inserito all’interno di una sezione, aggiungere anche il relativo ID a filters[0].components di models/_section.json:

"estimated-delivery"

models/_component-models.json non ha bisogno di questo trattamento. Include automaticamente ogni blocco tramite un carattere jolly, ../blocks/*/_*.json#/models, pertanto il solo schema del campo del blocco è sufficiente per raggiungere component-models.json. models/_component-definition.json e models/_section.json non utilizzano un carattere jolly per questo progetto, pertanto un nuovo blocco è invisibile nel selettore finché non viene aggiunto ad entrambi per nome, anche se il relativo modello viene compilato correttamente.

Compila entrambe le modifiche nei file aggregati del progetto (component-definition.json, component-filters.json e component-models.json), descritti in Genera il progetto JSON.

Implementare il blocco

File da aggiungere

blocks/estimated-delivery/
├── _estimated-delivery.json   # the block model, shown above
├── estimated-delivery.js      # decorate() renders the form and result states
└── estimated-delivery.css     # form layout and result state styling

Rendering del modulo e risultato di un segnaposto

Creare la funzione decorate() per eseguire il rendering di una selezione di prodotto, un input di codice postale, un pulsante di invio e un’area dei risultati vuota. Per il momento, mantieni il gestore di invio come stub.

readBlockContent() legge i due campi creati dal DOM del blocco. Universal Editor esegue il rendering di ogni campo modello come elemento secondario <div> nell’ordine dei campi, quindi l’intestazione è il testo del primo elemento secondario e l’etichetta del pulsante è quella del secondo, tornando a un valore predefinito quando un campo è vuoto:

// blocks/estimated-delivery/estimated-delivery.js
const DEFAULTS = {
  title: 'When will it arrive?',
  ctaText: 'Check estimated delivery',
};

const PRODUCTS = [
  { value: 'house-blend-medium-roast', label: 'House Blend - Medium Roast' },
  { value: 'frescopa-smart-machine', label: 'Fréscopa Smart Machine' },
  { value: 'insulated-travel-thermos', label: 'Insulated Travel Thermos' },
];

const PRODUCT_OPTIONS_HTML = PRODUCTS.map(
  (p) => `<option value="${p.value}">${p.label}</option>`,
).join('');

function getBlockText(el, fallback) {
  const text = el?.textContent?.trim();
  return text || fallback;
}

function readBlockContent(block) {
  const props = [...block.children].map((row) => row.firstElementChild);

  return {
    title: getBlockText(props[0], DEFAULTS.title),
    ctaText: getBlockText(props[1], DEFAULTS.ctaText),
  };
}

export default function decorate(block) {
  const { title, ctaText } = readBlockContent(block);

  block.innerHTML = `
    <div class="estimated-delivery">
      <h3 data-aue-prop="title" data-aue-label="Heading" data-aue-type="text">${title}</h3>
      <form class="estimated-delivery__form">
        <select name="sku">${PRODUCT_OPTIONS_HTML}</select>
        <input name="postcode" type="text" placeholder="e.g. 10001" required />
        <button type="submit" data-aue-prop="ctaText" data-aue-label="CTA Text" data-aue-type="text">${ctaText}</button>
      </form>
      <div class="estimated-delivery__result" aria-live="polite">
        <p>Select a product, enter your postcode, and click the button.</p>
      </div>
    </div>
  `;

  // form submit logic added in the next step
}

data-aue-prop, data-aue-label e data-aue-type contrassegnano il testo dell’intestazione e del pulsante come campi modificabili nell’editor universale, lo stesso pattern utilizzato in Crea un blocco. Questo è lo scaffold, non il file finale. L’implementazione di riferimento estimated-delivery.js include anche la logica di recupero da Connetti il blocco alla funzione Edge di AEM, che collega al file completo una volta che tale logica è presente.

Personalizzare lo stile del blocco

Aggiungi CSS per il layout del modulo, lo stato del segnaposto e gli stati dei risultati il rendering del blocco Edge Delivery Services viene eseguito successivamente (caricamento, errore, operazione riuscita), dopo Sviluppa un blocco con CSS e JavaScript. Estratto rappresentativo da estimated-delivery.css:

/* blocks/estimated-delivery/estimated-delivery.css */
.estimated-delivery__form {
  display: grid;
  gap: var(--spacing-small);
  padding: var(--spacing-medium);
  background: #fff;
  border-radius: 12px;
  box-shadow: 0 4px 12px rgb(0 0 0 / 6%);
}

.estimated-delivery__placeholder {
  display: grid;
  gap: var(--spacing-xsmall);
  align-content: center;
  border: 2px dashed var(--color-neutral-400);
  border-radius: 12px;
  text-align: center;
}

Nel file completo viene inoltre applicato lo stile al dispositivo di selezione del caricamento e ai colori dello stato della scheda di operazione riuscita (in-stock, low-stock, out-of-stock), che il blocco Edge Delivery Services non riproduce fino a Connettere il blocco alla funzione Edge di AEM.

Invia il codice e crea il blocco

Visualizzare l’anteprima locale del blocco

Esegui il sito Edge Delivery Services localmente e conferma il rendering del segnaposto prima di attivare la chiamata di recupero.

$ aem up

Aprire la pagina creata in http://localhost:3000/dev/branches/estimated-delivery e confermare il rendering del testo di intestazione, modulo e segnaposto come creato. Il pulsante Invia non esegue ancora alcuna operazione.

Passaggi successivi

In Connetti il blocco alla funzione Edge di AEM, puoi collegare il blocco Edge Delivery Services alla funzione Edge di AEM creata nel passaggio precedente, sostituendo il risultato segnaposto con dati live.

Risorse aggiuntive