Creare un nuovo blocco

In questo capitolo viene descritto come creare un nuovo blocco teaser modificabile per un sito web Edge Delivery Services tramite l’editor universale.

Il blocco, denominato teaser, presenta i seguenti elementi:

Il contenuto del blocco teaser può essere modificato nell’editor universale per garantirne la facilità d’uso e di riutilizzo in tutto il sito web.

Come puoi osservare, il blocco teaser è simile al blocco standard hero; pertanto il blocco teaser è inteso solo come semplice esempio per illustrare i concetti di sviluppo.

Creare un nuovo ramo Git

Per mantenere un flusso di lavoro pulito e organizzato, crea un nuovo ramo per ogni attività di sviluppo specifica. Questo ti aiuterà a evitare problemi di implementazione in produzione di codice incompleto o non testato.

# ~/Code/aem-wknd-eds-ue

$ git fetch origin
$ git checkout -b teaser origin/main

Una volta creato il ramo teaser, puoi iniziare a sviluppare il blocco Teaser.

Cartella del blocco

Crea una nuova cartella denominata teaser nella directory blocks del progetto. Questa cartella contiene i file JSON, CSS e JavaScript del blocco, organizzando tutti i file del blocco in un’unica posizione:

# ~/Code/aem-wknd-eds-ue

/blocks/teaser

Il nome della cartella del blocco funge da ID del blocco e viene utilizzato per farvi riferimento durante lo sviluppo.

File JSON del blocco

Il file JSON del blocco ne definisce tre aspetti chiave:

Crea un nuovo file in /blocks/teaser/_teaser.json con la seguente struttura iniziale, nell’ordine esatto riportato di seguito. Se le chiavi non sono nell’ordine corretto, potrebbero non essere create correttamente.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nome file dell’esempio di codice riportato di seguito."}

{
    "definitions": [],
    "models": [],
    "filters": []
}

Modello di blocco

Il modello di blocco è una parte critica della configurazione del blocco, in quanto definisce:

Ai modelli viene assegnato un id che corrisponde alla definizione del blocco e include un array fields per specificare i campi modificabili.

Ogni campo nell’array fields ha un oggetto JSON che include le seguenti proprietà obbligatorie:

Per un elenco completo delle proprietà, incluse quelle facoltative, consulta la documentazione dei campi dell’editor universale.

Progettazione del blocco

Il blocco teaser include i seguenti elementi modificabili:

La progettazione del blocco teaser è suddivisa in questi due componenti logici (contenuto immagine e testo), garantendo un’esperienza di authoring strutturata e intuitiva per gli utenti.

Campi del blocco

Definisci i campi necessari per il blocco: immagine, testo alternativo per l’immagine, testo, etichetta CTA e collegamento CTA.

{
    "definitions": [],
    "models": [
        {
            "id": "teaser",
            "fields": [
                {
                    "component": "reference",
                    "valueType": "string",
                    "name": "image",
                    "label": "Image",
                    "multi": false
                },
                {
                    "component": "text",
                    "valueType": "string",
                    "name": "imageAlt",
                    "label": "Image alt text",
                    "required": true
                },
                {
                    "component": "richtext",
                    "name": "textContent_text",
                    "label": "Text",
                    "valueType": "string",
                    "required": true
                },
                {
                    "component": "aem-content",
                    "name": "textContent_cta",
                    "label": "CTA",
                    "valueType": "string"
                },
                {
                    "component": "text",
                    "name": "textContent_ctaText",
                    "label": "CTA label",
                    "valueType": "string"
                }
            ]
        }
    ],
    "filters": []
}

<div>
    <div>
        <!-- This div contains the field-collapsed image fields  -->
        <picture>
            ...
            <source .../>
            <img src="..." alt="The authored alt text"/>
        </picture>
    </div>
    <div>
        <!-- This div, via element grouping contains the textContent fields -->
        <h2>The authored title</h2>
        <p>The authored body text</p>
        <a href="/authored/cta/link">The authored CTA label</a>
    </div>
</div>

{
    "definitions": [],
    "models": [
        {
            "id": "teaser",
            "fields": [
                {
                    "component": "reference",
                    "valueType": "string",
                    "name": "image",
                    "label": "Image",
                    "multi": false
                },
                {
                    "component": "text",
                    "valueType": "string",
                    "name": "alt",
                    "label": "Image alt text",
                    "required": true
                },
                {
                    "component": "richtext",
                    "name": "text",
                    "label": "Text",
                    "valueType": "string",
                    "required": true
                },
                {
                    "component": "aem-content",
                    "name": "link",
                    "label": "CTA",
                    "valueType": "string"
                },
                {
                    "component": "text",
                    "name": "label",
                    "label": "CTA label",
                    "valueType": "string"
                }
            ]
        }
    ],
    "filters": []
}

<div>
    <div>
        <!-- This div contains the field-collapsed image  -->
        <picture>
            ...
            <source .../>
            <img src="/authored/image/reference"/>
        </picture>
    </div>
    <div>
        <p>The authored alt text</p>
    </div>
    <div>
        <h2>The authored title</h2>
        <p>The authored body text</p>
    </div>
    <div>
        <a href="/authored/cta/link">/authored/cta/link</a>
    </div>
    <div>
        The authored CTA label
    </div>
</div>

Definizione del blocco

La definizione del blocco registra il blocco nell’editor universale. Di seguito trovi le proprietà JSON utilizzate nella definizione del blocco:

Di seguito è riportato un esempio di codice JSON per la definizione del blocco:

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nome file dell’esempio di codice riportato di seguito."}

{
    "definitions": [{
      "title": "Teaser",
      "id": "teaser",
      "plugins": {
        "xwalk": {
          "page": {
            "resourceType": "core/franklin/components/block/v1/block",
            "template": {
              "name": "Teaser",
              "model": "teaser",
              "textContent_text": "<h2>Enter a title</h2><p>...and body text here!</p>",
              "textContent_cta": "/",
              "textContent_ctaText": "Click me!"
            }
          }
        }
      }
    }],
    "models": [... from previous section ...],
    "filters": []
}

In questo esempio:

Con questa struttura, nell’editor universale il blocco sarà configurato con i campi, il modello di contenuto e il tipo di risorsa giusti per consentirne la corretta riproduzione.

Filtri del blocco

L’array filters del blocco definisce, per i blocchi contenitore, quali altri blocchi possono essere aggiunti al contenitore. I filtri definiscono un elenco di ID di blocco (model.id) che possono essere aggiunti al contenitore.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nome file dell’esempio di codice riportato di seguito."}

{
  "definitions": [... populated from previous section ...],
  "models": [... populated from previous section ...],
  "filters": []
}

Il componente teaser non è un blocco contenitore, pertanto non è possibile aggiungervi altri blocchi. Di conseguenza, l’array filters è lasciato vuoto. Piuttosto, aggiungi invece l’ID del teaser all’elenco dei filtri di un blocco sezione, in modo che possa essere aggiunto a una sezione.

I filtri dei blocchi forniti da Adobe, ad esempio il blocco sezione, sono memorizzati nella cartella models del progetto. Per modificarli, individua il file JSON del blocco fornito da Adobe (ad esempio, /models/_section.json) e aggiungi l’ID del teaser (teaser) all’elenco dei filtri. Questa configurazione segnala all’editor universale che il componente teaser può essere aggiunto al blocco contenitore “section”.

[/models/_section.json]{class="badge neutral" title="Nome file dell’esempio di codice riportato di seguito."}

{
  "definitions": [],
  "models": [],
  "filters": [
    {
      "id": "section",
      "components": [
        "text",
        "image",
        "button",
        "title",
        "hero",
        "cards",
        "columns",
        "fragment",
        "teaser"
      ]
    }
  ]
}

L’ID di definizione del blocco teaser teaser è stato aggiunto all’array components.

Eseguire il linting dei file JSON

Assicurati di eseguire frequentemente il linting per le modifiche apportate, per assicurarti che il codice pulito e coerente. Eseguendo frequentemente il linting si possono individuare per tempo eventuali problemi, velocizzando così i tempi di sviluppo. Il comando npm run lint:js eseue il linting anche sui file JSON e rileva eventuali errori di sintassi.

# ~/Code/aem-wknd-eds-ue

$ npm run lint:js

Creare il progetto JSON

Dopo aver configurato i file JSON del blocco (ad esempio, blocks/teaser/_teaser.json e models/_section.json), questi vengono compilati automaticamente nei file component-models.json, component-definitions.json e component-filters.json del progetto. La compilazione viene gestita automaticamente da un hook pre-commit Husky incluso nel modello del progetto AEM Boilerplate XWalk.

Le build possono anche essere attivate manualmente o a livello di programmazione tramite gli script NPM con codice “build” di JSON del progetto.

Implementare il blocco JSON

Per rendere il blocco disponibile nell’editor universale, è necessario eseguire il commit del progetto e inviarlo al ramo di un archivio GitHub, in questo caso il ramo teaser.

Il nome esatto del ramo utilizzato dall’editor universale può essere regolato, per utente, tramite il suo URL.

# ~/Code/aem-wknd-eds-ue

$ git add .
$ git commit -m "Add teaser block JSON files so it is available in Universal Editor"
# JSON files are compiled automatically and added to the commit via a husky precommit hook
$ git push origin teaser

Quando si apre l’editor universale con il parametro di query ?ref=teaser, il nuovo blocco teaser viene visualizzato nella palette dei blocchi. Il blocco non ha uno stile; i campi del blocco vengono riprodotti come HTML semantico, e formattati solo tramite il CSS globale.