Erstellen eines neuen Blocks

In diesem Kapitel wird der Prozess zum Erstellen eines neuen, bearbeitbaren Teaser-Blocks für eine Edge Delivery Services-Website mit dem universellen Editor beschrieben.

Der Block mit dem Namen teaser zeigt die folgenden Elemente:

Der Inhalt des teaser-Blocks kann im universellen Editor bearbeitet werden, wodurch die Benutzerfreundlichkeit und Wiederverwendbarkeit auf der gesamten Website gewährleistet ist.

Beachten Sie, dass der teaser-Block dem hero-Block des Textbausteins ähnelt; daher soll der teaser-Block nur als einfaches Beispiel zur Veranschaulichung von Entwicklungskonzepten dienen.

Erstellen einer neuen Git-Verzweigung

Um einen sauberen und organisierten Workflow beizubehalten, erstellen Sie für jede spezifische Entwicklungsaufgabe eine neue Verzweigung. Dadurch werden Probleme mit einer Bereitstellung von unvollständigem oder ungetestetem Code in der Produktion vermieden.

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

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

Sobald die teaser-Verzweigung erstellt ist, können Sie mit der Entwicklung des Teaser-Blocks beginnen.

Block-Ordner

Erstellen Sie einen neuen Ordner mit dem Namen teaser im blocks-Verzeichnis des Projekts. Dieser Ordner enthält die JSON-, CSS- und JavaScript-Dateien des Blocks, wobei die Dateien des Blocks an einem selben Speicherort organisiert werden:

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

/blocks/teaser

Der Name des Blockordners fungiert als ID des Blocks und wird verwendet, um während der Entwicklung des Blocks auf diesen zu verweisen.

Block-JSON

Die Block-JSON definiert drei wichtige Aspekte des Blocks:

Erstellen Sie eine neue Datei /blocks/teaser/_teaser.json mit der folgenden anfänglichen Struktur in der exakten Reihenfolge. Wenn die Schlüssel nicht in der richtigen Reihenfolge vorliegen, werden sie möglicherweise nicht ordnungsgemäß erstellt.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Dateiname des unten stehenden Code-Beispiels."}

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

Blockmodell

Das Blockmodell ist ein wichtiger Teil der Konfiguration des Blocks, da es Folgendes definiert:

Modellen wird eine id zugewiesen, die der Definition des Blocks entspricht, und sie enthalten ein fields-Array zur Angabe der bearbeitbaren Felder.

Jedes Feld in diesem fields-Array verfügt über ein JSON-Objekt, das die folgenden erforderlichen Eigenschaften enthält:

Eine umfassende Liste der Eigenschaften, einschließlich der optionalen Eigenschaften, finden Sie in der Dokumentation zu den Feldern des universellen Editors.

Design des Blocks

Der Teaser-Block enthält die folgenden bearbeitbaren Elemente:

Das Design des Teaser-Blocks ist in diese beiden logischen Komponenten (Bild- und Textinhalt) unterteilt, sodass Benutzende ein strukturiertes und intuitives Authoring-Erlebnis erhalten.

Felder des Blocks

Definieren Sie die für den Block erforderlichen Felder: Bild, Alternativtext für Bilder, Text, CTA-Label und CTA-Link.

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

Blockdefinition

Die Blockdefinition registriert den Block im universellen Editor. Im Folgenden finden Sie eine Aufschlüsselung der in der Blockdefinition verwendeten JSON-Eigenschaften:

Im Folgenden finden Sie eine Beispiel-JSON für die Blockdefinition:

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Dateiname des unten stehenden Code-Beispiels."}

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

Beschreibung dieses Beispiels:

Durch diese Struktur wird sichergestellt, dass der Block im universellen Editor mit den richtigen Feldern, dem Inhaltsmodell und dem Ressourcentyp für das Rendering eingerichtet wird.

Blockfilter

Das filters-Array des Blocks definiert für Container-Blöcke, welche anderen Blöcke zum Container hinzugefügt werden können. Filter definieren eine Liste von Block-IDs (model.id), die dem Container hinzugefügt werden können.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Dateiname des unten stehenden Code-Beispiels."}

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

Die Teaser-Komponente ist kein Container-Block, d. h., Sie können ihr keine anderen Blöcke hinzufügen. Daher bleibt das filters-Array leer. Fügen Sie stattdessen die Teaser-ID zur Filterliste des Abschnittsblocks hinzu, sodass der Teaser zu einem Abschnitt hinzugefügt werden kann.

Von Adobe bereitgestellte Blöcke, wie etwa der Abschnittsblock, speichern Filter im models-Ordner des Projekts. Suchen Sie zum Anpassen die JSON-Datei für den von Adobe bereitgestellten Block (z. B. /models/_section.json) und fügen Sie die Teaser-ID (teaser) zur Filterliste hinzu. Die Konfiguration signalisiert dem universellen Editor, dass die Teaser-Komponente zum Abschnitts-Container-Block hinzugefügt werden kann.

[/models/_section.json]{class="badge neutral" title="Dateiname des unten stehenden Code-Beispiels."}

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

Die ID der Teaser-Blockdefinition von teaser wird dem components-Array hinzugefügt.

Linten der JSON-Dateien

Achten Sie darauf, dass Sie Ihre Änderungen häufig linten, um sicherzustellen, dass sie sauber und konsistent sind. Häufiges Linten hilft, Probleme frühzeitig zu erkennen, und reduziert die allgemeine Entwicklungszeit. Der Befehl npm run lint:js lintet auch JSON-Dateien und erkennt Syntaxfehler.

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

$ npm run lint:js

Erstellen der Projekt-JSON

Nach dem Konfigurieren der JSON-Blockdateien (blocks/teaser/_teaser.json, models/_section.json) werden sie automatisch in die Dateien component-models.json, component-definitions.json und component-filters.json des Projekts kompiliert. Diese Kompilierung wird automatisch von einem Husky-Pre-Commit-Hook durchgeführt, der in der AEM Boilerplate XWalk-Projektvorlage enthalten ist.

Builds können auch manuell oder programmgesteuert mithilfe der NPM-Skripte für die Erstellungs-JSON des Projekts ausgelöst werden.

Bereitstellen der Block-JSON

Um den Block im universellen Editor verfügbar zu machen, muss das Projekt an die Verzweigung des GitHub-Repositorys übertragen werden, in diesem Fall an die teaser-Verzweigung.

Der genaue Name der Verzweigung, den der universelle Editor verwendet, kann für jede Benutzerin und jeden Benutzer über die URL des universellen Editors angepasst werden.

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

Wenn der universelle Editor mit dem Abfrageparameter ?ref=teaser geöffnet wird, erscheint der neue teaser-Block in der Blockpalette. Beachten Sie, dass der Block keine Formatierung aufweist, sondern die Felder des Blocks als semantische HTML rendert, die nur über das globale CSS formatiert wird.