Créer un bloc

Ce chapitre décrit le processus de création d’un bloc de teaser modifiable pour un site web Edge Delivery Services à l’aide de l’éditeur universel.

Le bloc, nommé teaser, présente les éléments suivants :

Le contenu du bloc teaser est modifiable dans l’éditeur universel, ce qui garantit sa facilité d’utilisation et de réutilisation sur l’ensemble du site web.

Notez que le bloc teaser est similaire au bloc hero du modèle standard. Par conséquent, le bloc teaser n’est destiné qu’à servir d’exemple simple pour illustrer des concepts de développement.

Créer une branche Git

Pour maintenir un workflow propre et organisé, créez une branche pour chaque tâche de développement spécifique. Cela permet d’éviter les problèmes de déploiement de code incomplet ou non testé en production.

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

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

Une fois la branche teaser créée, vous êtes en mesure de commencer à développer le bloc de teaser.

Dossier de bloc

Créez un dossier nommé teaser dans le répertoire blocks du projet. Ce dossier contient les fichiers JSON, CSS et JavaScript du bloc, ce qui organise les fichiers du bloc en un seul emplacement :

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

/blocks/teaser

Le nom du dossier de blocs fait office d’identifiant du bloc et est utilisé pour référencer le bloc tout au long de son développement.

JSON de bloc

Le JSON de bloc définit trois aspects clés du bloc :

Créez un fichier à l’adresse /blocks/teaser/_teaser.json avec la structure initiale suivante, dans l’ordre exact. Si les clés ne sont pas dans le bon ordre, elles risquent de ne pas se construire correctement.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nom de fichier de l’exemple de code ci-dessous."}

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

Modèle de bloc

Le modèle de bloc constitue une partie essentielle de la configuration du bloc, dans la mesure où il définit les éléments suivants :

Les modèles se voient attribuer un élément id correspondant à la définition du bloc et incluent un tableau fields pour spécifier les champs modifiables.

Chaque champ du tableau fields comporte un objet JSON qui inclut les propriétés requises suivantes :

Pour obtenir la liste complète des propriétés, y compris les propriétés facultatives, consultez la documentation des champs de l’éditeur universel.

Conception de bloc

Le bloc de teaser comprend les éléments modifiables suivants :

La conception du bloc de teaser est divisée en ces deux composants logiques (contenu d’image et de texte), ce qui garantit une expérience de création structurée et intuitive pour les utilisateurs et les utilisatrices.

Champs de bloc

Définissez les champs requis pour le bloc : image, texte secondaire de l’image, texte, libellé CTA et lien 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>

Définition du bloc

La définition de bloc enregistre le bloc dans l’éditeur universel. Voici une répartition des propriétés JSON utilisées dans la définition de bloc :

Voici un exemple JSON pour la définition de bloc :

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nom de fichier de l’exemple de code ci-dessous."}

{
    "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": []
}

Dans cet exemple :

Cette structure garantit que le bloc est configuré dans l’éditeur universel avec les champs, le modèle de contenu et le type de ressource appropriés pour le rendu.

Filtres de bloc

Le tableau de filters du bloc définit, pour les blocs de conteneur, les autres blocs qui peuvent être ajoutés au conteneur. Les filtres définissent une liste d’identifiants de bloc (model.id) qui peuvent être ajoutés au conteneur.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Nom de fichier de l’exemple de code ci-dessous."}

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

Le composant Teaser n’est pas un bloc de conteneur, ce qui signifie que vous ne pouvez pas y ajouter d’autres blocs. Par conséquent, son tableau filters reste vide. Au lieu de cela, ajoutez l’identifiant du teaser à la liste de filtres du bloc de section, de sorte que le teaser puisse être ajouté à une section.

Les blocs fournis par Adobe, tels que le bloc de section, stockent les filtres dans le dossier models du projet. Pour effectuer des réglages, recherchez le fichier JSON pour le bloc fourni par Adobe (par exemple, /models/_section.json) et ajoutez l’identifiant du teaser (teaser) à la liste des filtres. La configuration indique à l’éditeur universel que le composant Teaser peut être ajouté au bloc de conteneur de section.

[/models/_section.json]{class="badge neutral" title="Nom de fichier de l’exemple de code ci-dessous."}

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

L’identifiant de définition de bloc de teaser teaser est ajouté au tableau components.

Appliquer lint à vos fichiers JSON

Veillez à appliquer lint fréquemment à vos modifications afin qu’elles soient claires et cohérentes. L’application fréquente de lint permet de détecter les problèmes tôt et réduit le temps de développement global. La commande npm run lint:js applique également lint aux fichiers JSON et détecte toute erreur de syntaxe.

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

$ npm run lint:js

Créer le JSON de projet

Après la configuration des fichiers JSON du bloc (par exemple, blocks/teaser/_teaser.json, models/_section.json), ils sont automatiquement compilés dans les fichiers component-models.json, component-definitions.json et component-filters.json du projet. Cette compilation est gérée automatiquement par un hook de pré-validation Husky inclus dans le modèle de projet AEM Boilerplate XWalk.

Les générations peuvent également être déclenchées manuellement ou par programmation à l’aide des scripts NPM de génération JSON du projet.

Déployer le JSON de bloc

Pour rendre le bloc disponible dans l’éditeur universel, le projet doit être validé et placé dans la branche d’un référentiel GitHub, dans ce cas la branche teaser.

Le nom de branche exact qu’utilise l’éditeur universel peut être ajusté, par utilisateur ou utilisatrice, via l’URL de l’éditeur universel.

# ~/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

Lorsque l’éditeur universel est ouvert avec le paramètre de requête ?ref=teaser, le nouveau bloc teaser apparaît dans la palette du bloc. Notez que le bloc n’a pas de style : il effectue le rendu des champs du bloc en tant que code HTML sémantique, stylisé uniquement via le CSS global.