---
title: Ex3: Create a Block Definition
slug: saga-hol/ex3-create-a-block-definition
createdAt: 2026-08-12T12:08:57.101Z
---

*In this lab, you will create a custom **Quote** block for an AEM Edge Delivery Services project. You will define the block, add it to an AEM page using the Universal Editor, style it with JavaScript and CSS, and publish the result.*

## What You’ll Learn

By the end of this lab, you will be able to:

- Define a custom block in an AEM EDS project.
- Add the block to an existing page using the Universal Editor.
- Decorate the block with JavaScript.
- Style the block with CSS.
- Commit and publish your changes.



## Part 1 — Clone Your GitHub Project locally

Clone the project repository to your local system. Working locally makes it easier to edit files, test changes, and commit your work. Here we will be using VSCode, but you can use any familiar IDE.&#x20;

1. **Clone your repository** locally with your preferred method :

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/6RfTHS8vaF5oVdoaMWd5i_image.png" size="100" isUploading="false" width="1584" height="787" darkWidth="1584" darkHeight="787" showCaption="false" indent="1"}

2. Open the project folder in your IDE, here we will use VSCode:

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/BZlOthMsD13X4Hc9HEBRO_image.png" size="100" isUploading="false" width="1337" height="788" darkWidth="1337" darkHeight="788" showCaption="false" indent="1"}

:::hint{type="info"}
You can also edit the repository directly in GitHub:

1. Open the file you want to edit.
2. Select the **Edit** pencil icon.
3. Make your changes.
4. Commit the changes directly to the repository.

![](https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/iBK_0RdvVRsIdbsjzthmX_image.png)
:::



## Part 2 — How the project is structured

The repository contains many folders, but this lab only uses a few of them. The most important one will be **Blocks** which contains all Blocks definitions.&#x20;

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/j4yTrDgiOlBvp27RvWMBo_image.png" size="30" isUploading="false" width="331" height="791" darkWidth="331" darkHeight="791" showCaption="false"}

Here is the simplified architecture:

:::BlockQuote
\<your-site-repo>/
├── blocks/
│   └── quote-lab/
│       ├── \_quote-lab.json
│       ├── quote-lab.js
│       └── quote-lab.css
│
├── models/
│   └── \_section.json
│
├── styles/
│   └── global site styles
│
├── component-definition.json
├── component-models.json
├── component-filters.json
└── package.json
:::

### Important folders and files

| **Location**                          | **Purpose**                                                   |
| ------------------------------------- | ------------------------------------------------------------- |
| **blocks/**                           | Contains the code and authoring definition for each block.    |
| blocks/quote-lab/**\_quote-lab.json** | Defines the block, its fields, and its default content.       |
| blocks/quote-lab/**quote-lab.js**     | Converts the authored content into the final HTML structure.  |
| blocks/quote-lab/**quote-lab.css**    | Controls the visual appearance of the block.                  |
| models/**\_section.json**             | Controls which blocks can be added inside a section.          |
| **styles/**                           | Contains global styles and design variables used by the site. |
| **component-\*.json**                 | Generated files. Do not edit these files manually.            |
| **package.json**                      | Contains project commands such as npm run build\:json.        |



## Part 3 — Define the Block

1. Create the block folder named `quote-lab`, in`/blocks`:

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/pKtuQWVlRGReDKMm6IIma_image.png" size="40" isUploading="false" width="468" height="252" darkWidth="468" darkHeight="252" showCaption="false" indent="1"}

2. Create the block configuration file in this folder, named `_quote-lab.json`:

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/cSv-dDNjxtUXF83inlTmJ_image.png" size="40" isUploading="false" width="476" height="322" darkWidth="476" darkHeight="322" showCaption="false" indent="1"}

3. And paste this content in `_quote-lab.json`:

   ```json
   {
     "definitions": [
       {
         "title": "Quote Lab",
         "id": "quote-lab",
         "plugins": {
           "xwalk": {
             "page": {
               "resourceType": "core/franklin/components/block/v1/block",
               "template": {
                 "name": "Quote Lab",
                 "model": "quote-lab",
                 "quote": "<p>Great digital experiences should feel simple, clear, and human.</p>",
                 "author": "NatWest Digital Experience Team"
               }
             }
           }
         }
       }
     ],
     "models": [
       {
         "id": "quote-lab",
         "fields": [
           {
             "component": "richtext",
             "name": "quote",
             "value": "",
             "label": "Quote",
             "valueType": "string"
           },
           {
             "component": "text",
             "name": "author",
             "label": "Author",
             "value": "",
             "valueType": "string"
           }
         ]
       }
     ],
     "filters": []
   }
   ```

::::hint{type="info"}
### What does this file do?

The file contains the complete Universal Editor configuration for the block.

**Definitions**

The definition registers the block:

:::BlockQuote
\{
&#x20; "title": "Quote Lab",
&#x20; "id": "quote-lab"
}
:::

- title is the name displayed to authors.
- id is the technical identifier used by the project.
- The id must be unique. This is why we use quote-lab instead of quote.

The template provides sample content that can be used when the block is first inserted:

:::BlockQuote
"template": \{
&#x20; "name": "Quote Lab",
&#x20; "model": "quote-lab",
&#x20; "quote": "...",
&#x20; "author": "..."
}
:::

**Models**

The model defines the fields displayed in Universal Editor:

:::BlockQuote
\{
&#x20; "component": "richtext",
&#x20; "name": "quote",
&#x20; "label": "Quote",
&#x20; "valueType": "string"
}
:::

This creates an editable rich-text field named quote.

The second field creates a simple text input for the author:

:::BlockQuote
\{
&#x20; "component": "text",
&#x20; "name": "author",
&#x20; "label": "Author",
&#x20; "valueType": "string"
}
:::

The field names are important. The JavaScript implementation will also refer to the first row as the quote and the second row as the author.

**Filters**

The block is not a container, so it does not need to define its own filter:

:::BlockQuote
"filters": \[]
:::

The section filter will be updated separately to allow this block to be inserted into a section.
::::



## Part 4 — Add the block to the section filter

1. Open `models/_section.json`and find the existing components array. It look similar to this:

:::BlockQuote{indent="1"}
\{
&#x20; "id": "section",
&#x20; "components": \[
&#x20;   "text",
&#x20;   "image",
&#x20;   "button",
&#x20;   "title",
&#x20;   "hero",
&#x20;   "cards",
&#x20;   "columns",
&#x20;   "quote"
&#x20; ]
}
:::

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/DoKXW9jnVRdHWUINCA7gY_image.png" size="100" isUploading="false" width="1562" height="1118" darkWidth="1562" darkHeight="1118" showCaption="false" indent="1"}

2. Add `quote-lab` to this components array:

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/law-D2sG9hTmezT6N5Nkd_image.png" size="50" isUploading="false" width="584" height="272" darkWidth="584" darkHeight="272" showCaption="false" indent="1"}

:::hint{type="danger" indent="1"}
Keep the other existing components. Do not replace the entire file.
:::

:::hint{type="info" indent="1"}
### Why is this file different?

The block JSON registers quote-lab, but the section filter controls whether the block is available inside a section.

In other words:

- \_quote-lab.json says: “This block exists.”
- \_section.json says: “This block may be added inside a section.”
:::



## Part 5 — Build and publish the block definition

1. **Install the project dependencies**, in the terminal, **run : `npm install`**
2. Generate the aggregate JSON files, by **running**: `npm run build:json`

::::hint{type="info" indent="1"}
This command reads the source JSON fragments and regenerates the aggregate files used by the project, such as:

:::BlockQuote
component-definition.json
component-models.json
component-filters.json
:::
::::

| :inlineImage[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/2VcSvubAJJS2QaMkacJaJ_image.png" alt caption} | :inlineImage[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/aYKyQZI3SkJi1iMx8MYk9_image.png" alt caption} |
| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |

:::hint{type="info" indent="1"}
**Why are we doing this?**
The root JSON files are generated artifacts. They allow the project to expose all block definitions, models, and filters in the format expected by Universal Editor.
:::



## Part 6 — Validate the changes and commit

1. Check the working tree with : `git status` and `git diff`. Or verify direclty in IDE that:&#x20;
   1. These 5 files are modified.&#x20;
   2. blocks/quote-lab/\_quote-lab.json exists.
   3. There are no accidental changes to unrelated files.

::Image[]{src="https://api.archbee.com/api/optimize/1Jp0iolWv35Z_mkI7oUiT/Y_w4Gpxs2tSRnfBWEpkZE_image.png" size="50" isUploading="false" width="700" height="584" darkWidth="700" darkHeight="584" showCaption="false"}

2. Add the source and generated files:

   ```bash
   git add blocks/quote-lab/_quote-lab.json
   git add models/_section.json
   git add component-definition.json
   git add component-models.json
   git add component-filters.json
   ```
3. And commit the changes:

:::CodeblockTabs{indent="1"}
```bash
git commit -m "Add NatWest quote lab block definition"
```
:::

4. Push the changes to main:

   ```bash
   git push -u origin main
   ```

:::hint{type="success"}
### Why must the changes be pushed?

Universal Editor uses the project configuration available in the GitHub branch connected to AEM.

When you push your changes, **AEM Code Sync automatically synchronizes the updated files with AEM**. Once the synchronization is complete, the **new block definition becomes available in Universal Editor.**

`The workflow is:`

1. `Create or update the block files locally.`
2. `Run the required build command, if applicable.`
3. `Commit and push the changes to GitHub.`
4. `Wait for AEM Code Sync to process the changes.`
5. `Open or refresh Universal Editor and select the new block.`

This also allows you to test the block from your development branch before merging it into the production branch.
:::









****
