Skapa ett nytt block

I det här kapitlet beskrivs hur du skapar ett nytt, redigerbart teaserblock för en Edge Delivery Services-webbplats med den universella redigeraren.

Blocket teaser visar följande element:

teaser-blockets innehåll kan redigeras i Universell redigerare vilket gör det enkelt att använda och återanvända på hela webbplatsen.

Observera att teaser-blocket liknar mallens hero-block. teaser-blocket är därför endast avsett att fungera som ett enkelt exempel för att illustrera utvecklingskoncept.

Skapa en ny Git-gren

Om du vill ha ett rent och organiserat arbetsflöde skapar du en ny gren för varje specifik utvecklingsuppgift. På så sätt undviker du problem med att distribuera ofullständig eller otestad kod till produktionen.

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

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

När grenen teaser har skapats kan du börja utveckla teaserblocket.

Blockera mapp

Skapa en ny mapp med namnet teaser i projektkatalogen blocks. Den här mappen innehåller blockets JSON-, CSS- och JavaScript-filer och ordnar blockets filer på en plats:

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

/blocks/teaser

Blockmappens namn fungerar som blockets ID och används för att referera till blocket under hela dess utveckling.

Blockera JSON

Blocket JSON definierar tre huvudaspekter av blocket:

Skapa en ny fil på /blocks/teaser/_teaser.json med följande inledande struktur, i exakt ordning. Om nycklarna inte är i ordning kanske de inte byggs som de ska.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Filnamn på kodexemplet nedan."}

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

Blockmodell

Blockmodellen är en viktig del av blockets konfiguration, eftersom den definierar:

Modeller tilldelas en id som motsvarar blockets definition och innehåller en fields-array som anger de redigerbara fälten.

Varje fält i arrayen fields har ett JSON-objekt som innehåller följande obligatoriska egenskaper:

En omfattande lista med egenskaper, inklusive valfria, finns i dokumentationen för fält i den universella redigeraren.

Blockdesign

Teaser-blocket innehåller följande redigerbara element:

Teaser-blockets design är uppdelad i två logiska komponenter (bild- och textinnehåll), vilket ger en strukturerad och intuitiv redigeringsupplevelse för användarna.

Blockera fält

Definiera de fält som krävs för blocket: bild, bildalternativ text, text, CTA-etikett och CTA-länk.

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

Blockdefinitionen registrerar blocket i Universell redigerare. Här är en beskrivning av JSON-egenskaperna som används i blockdefinitionen:

Här är ett exempel på JSON för blockdefinitionen:

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Filnamn på kodexemplet nedan."}

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

I detta exempel:

Den här strukturen ser till att blocket är konfigurerat i den universella redigeraren med rätt fält, innehållsmodell och resurstyp för återgivning.

Blockfilter

Blockets filters-array definierar, för ​ behållarblock, vilka andra block som kan läggas till i behållaren. Filter definierar en lista med block-ID (model.id) som kan läggas till i behållaren.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="Filnamn på kodexemplet nedan."}

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

Teaser-komponenten är inte ett behållarblock, vilket innebär att du inte kan lägga till andra block i den. Därför är filters-arrayen tom. Lägg i stället till teaser-ID:t i avsnittsblockets filterlista så att teaser kan läggas till i ett avsnitt.

Adobe-fördefinierade block, som avsnittsblocket, lagrar filter i projektets models-mapp. Om du vill justera söker du efter JSON-filen för det Adobe-tillhandahållna blocket (till exempel /models/_section.json) och lägger till teaser-ID (teaser) i filterlistan. Konfigurationen signalerar till Universal Editor att teaser-komponenten kan läggas till i avsnittets behållarblock.

[/models/_section.json]{class="badge neutral" title="Filnamn på kodexemplet nedan."}

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

Teaser block definition ID för teaser läggs till i components-arrayen.

Laga dina JSON-filer

Se till att du ofta ​ lintar dina ändringar så att de blir rena och konsekventa. Linting hjälper dig att fånga upp problem tidigt och minskar den totala utvecklingstiden. Kommandot npm run lint:js begränsar också JSON-filer och fångar upp eventuella syntaxfel.

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

$ npm run lint:js

Bygg projekt-JSON

När blockets JSON-filer (t.ex. blocks/teaser/_teaser.json, models/_section.json) har konfigurerats kompileras de automatiskt till projektets component-models.json -, component-definitions.json - och component-filters.json -filer. Den här kompileringen hanteras automatiskt av en Husky-exekveringskrok som ingår i projektmallen AEM Boilerplate XWalk ​ .

Bygger kan också aktiveras manuellt eller programmatiskt med projektets build JSON NPM-skript.

Distribuera blockets JSON

Om du vill göra blocket tillgängligt i Universal Editor måste projektet implementeras och skickas till en GitHub-databasgren, i det här fallet grenen teaser.

Det exakta förgreningsnamnet Universal Editor använder kan justeras per användare via Universal Editors 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

När den universella redigeraren öppnas med frågeparametern ?ref=teaser visas det nya teaser-blocket på blockpaletten. Observera att blocket inte har någon formatering. Det återger blockets fält som semantiska HTML, formaterade endast via global CSS.