Ă۶ąĘÓƵ

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’s 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’s 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’re ready to start developing the teaser block.

Block folder

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

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

/blocks/teaser

The block folder name acts as the block’s 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’s configuration, as it defines:

Models are assigned an id that corresponds to the block’s 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’s 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’s a breakdown of the JSON properties used in the block definition:

Here’s 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’s 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’t a container block, meaning you can’t add other blocks to it. As a result, its filters array is left empty. Instead, add the teaser’s ID to the section block’s filter list, so the teaser can be added to a section.

Ă۶ąĘÓƵ-provided blocks, such as the section block, store filters in the project’s models folder. To adjust, locate the JSON file for the Ă۶ąĘÓƵ-provided block (for example, /models/_section.json) and add the teaser’s 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’s 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’s 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’s 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’s branch, in this case the teaser branch.

The exact branch name Universal Editor uses can be adjusted, per user, via the Universal Editor’s 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’s fields as semantic HTML, styled only via the global CSS.