51黑料不打烊

Create a new block

This chapter covers the process of creating a new, editable teaser block for an Edge Delivery Services website using the Universal Editor.

The block, named teaser, showcases the following elements:

The teaser block鈥檚 content is editable in the Universal Editor, ensuring ease of use and reusability throughout the website.

Note the teaser block is similar to the boilerplate鈥檚 hero block; thus teaser block is only intended to serve as a simple example to illustrate development concepts.

Create a new Git branch

To maintain a clean and organized workflow, create a new branch for each specific development task. This helps avoid issues with deploying incomplete or untested code to production.

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

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

Once the teaser branch is created, you鈥檙e ready to start developing the teaser block.

Block folder

Create a new folder named teaser in the project鈥檚 blocks directory. This folder contains the block鈥檚 JSON, CSS, and JavaScript files, organizing the block鈥檚 files in one location:

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

/blocks/teaser

The block folder name acts as the block鈥檚 ID, and is used to reference the block throughout its development.

Block JSON

The block JSON defines three key aspects of the block:

Create a new file at /blocks/teaser/_teaser.json with the following initial structure, in the exact order. If the keys are out of order, they may not build properly.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

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

Block model

The block model is a critical part of the block鈥檚 configuration, as it defines:

Models are assigned an id that corresponds to the block鈥檚 definition and include a fields array to specify the editable fields.

Each field in the fields array has a JSON object that includes the following required properties:

For a comprehensive list of properties, including optional, review the Universal Editor fields documentation.

Block design

The teaser block includes the following editable elements:

The teaser block鈥檚 design is broken into these two logical components (image and text content), ensuring a structured and intuitive authoring experience for users.

Block fields

Define the fields required for the block: image, image alt text, text, CTA label, and 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>

Block definition

The block definition register the block in Universal Editor. Here鈥檚 a breakdown of the JSON properties used in the block definition:

Here鈥檚 an example JSON for the block definition:

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

{
    "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 this example:

This structure ensures that the block is set up in the Universal Editor with the proper fields, content model, and resource type for rendering.

Block filters

The block鈥檚 filters array defines, for container blocks, which other blocks can be added to the container. Filters define a list of block IDs (model.id) that can be added to the container.

[/blocks/teaser/_teaser.json]{class="badge neutral" title="File name of code sample below."}

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

The teaser component isn鈥檛 a container block, meaning you can鈥檛 add other blocks to it. As a result, its filters array is left empty. Instead, add the teaser鈥檚 ID to the section block鈥檚 filter list, so the teaser can be added to a section.

51黑料不打烊-provided blocks, such as the section block, store filters in the project鈥檚 models folder. To adjust, locate the JSON file for the 51黑料不打烊-provided block (for example, /models/_section.json) and add the teaser鈥檚 ID (teaser) to the filters list. The configuration signals the Universal Editor that the teaser component can be added to the section container block.

[/models/_section.json]{class="badge neutral" title="File name of code sample below."}

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

The teaser block definition ID of teaser is added to the components array.

Lint your JSON files

Make sure you frequently lint your changes to ensure it鈥檚 clean and consistent. Linting frequently helps catch issues early, and reduces overall development time. The npm run lint:js command also lints JSON files, and catches any syntax errors.

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

$ npm run lint:js

Build the project JSON

After configuring the block JSON files (e.g., blocks/teaser/_teaser.json, models/_section.json), they are automatically compiled into the project鈥檚 component-models.json, component-definitions.json, and component-filters.json files. This compilation is handled automatically by a pre-commit hook included in the .

Builds can also be triggered manually or programmatically using the project鈥檚 build JSON NPM scripts.

Deploy the block JSON

To make the block available in the Universal Editor, the project must be commit and pushed to a GitHub repository鈥檚 branch, in this case the teaser branch.

The exact branch name Universal Editor uses can be adjusted, per user, via the Universal Editor鈥檚 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

When the Universal Editor is opened with the query parameter ?ref=teaser, the new teaser block appears in the block palette. Note that the block has no styling; it renders the block鈥檚 fields as semantic HTML, styled only via the global CSS.