Creating Blocks Instrumented for use with the Universal Editor create-block

Learn how to create blocks instrumented for use with the Universal Editor in WYSIWYG authoring with Edge Delivery Services projects.

Prerequisites prerequisites

This guide provides step-by-step instructions for how to create blocks instrumented for the Universal Editor in WYSIWYG authoring with Edge Delivery Services projects. It covers adding components, loading component definitions in the Universal Editor, publishing pages, implementing block decoration and styles, bringing the changes to production, and verifying them. Upon completing this guide, you can create and deploy a new block for your own project.

This guide necessarily requires existing knowledge of WYSIWYG authoring with Edge Delivery Services projects as well as the Universal Editor. Before beginning this guide, you should already have access to Edge Delivery Services and be familiar with its basics including:

This guide builds on the work done in the Developer Getting Started Guide for WYSIWYG authoring with Edge Delivery Services guide.

Adding a New Block to Your Project add-block

In this guide, you will build a block to render a memorable quote on your page.

To simplify this example, all changes are made to the main branch of the project repository. Of course for your actual project, you should follow development best practices by developing on a different branch and reviewing all changes via pull request before merging to main.

Adobe recommends that you develop blocks in a three-phased approach:

The following quote block example follows this approach.

Create Block Definition and Model create-block-model

1. Clone the GitHub project locally that you created in the Developer Getting Started Guide for WYSIWYG authoring with Edge Delivery Services guide and open it in an editor of your choice.

2. Edit the component-definition.json file at the root of the project and add the following definition for your new quote block and save the file.

JSON Example

code language-json
{ "title": "Quote", "id": "quote", "plugins": { "xwalk": { "page": { "resourceType": "core/franklin/components/block/v1/block", "template": { "name": "Quote", "model": "quote", "quote": "<p>Think, McFly! Think!</p>", "author": "Biff Tannen" } } } } }

Screenshot

3. Edit the component-models.json file at the root of the project and add the following model definition for your new quote block and save the file.

JSON Example

code language-json
{ "id": "quote", "fields": [ { "component": "richtext", "name": "quote", "value": "", "label": "Quote", "valueType": "string" }, { "component": "text", "valueType": "string", "name": "author", "label": "Author", "value": "" } ] }

Screenshot

4. Edit the component-filters.json file at the root of the project and add the quote block to the filter definition to allow the block to be added to any section and save the file.

JSON Example

code language-json
{ "id": "section", "components": [ "text", "image", "button", "title", "hero", "cards", "columns", "quote" ] }

Screenshot

5. Using git, commit these changes to your main branch.

Create Content with the Block create-content

Now that your basic quote block is defined and committed to the sample project, you can add a quote block to an existing page.

Style the Block style-block

Now that you have a working quote block you can apply styling to it.

1. Return to the editor for your project.

2. Create a quote folder under the blocks folder.

3. In the new quote folder, add a quote.js file to implement block decoration by adding the following JavaScript and save the file.

JavaScript Example

code language-javascript
export default function decorate(block) { const [quoteWrapper] = block.children; const blockquote = document.createElement('blockquote'); blockquote.textContent = quoteWrapper.textContent.trim(); quoteWrapper.replaceChildren(blockquote); }

Screenshot

4. In the quote folder, add a quote.css file to define the styling for the block by adding the following CSS code and save the file.

CSS Example

code language-css

.block.quote { background-color: #ccc; padding: 0 0 24px; display: flex; flex-direction: column; margin: 1rem 0; } .block.quote blockquote { margin: 16px; text-indent: 0; } .block.quote > div:last-child > div { margin: 0 16px; font-size: small; font-style: italic; position: relative; } .block.quote > div:last-child > div::after { content: ""; display: block; position: absolute; left: 0; bottom: -8px; height: 5px; width: 30px; background-color: darkgray; }

Screenshot

5. Using git, commit these changes to your main branch.

6. Return to your browser tab of the Universal Editor where you were editing the page of your project and reload the page to view your styled block.

7. See the now styled quote block on the page.

8. Verify that the changes were pushed to production by navigating to the published page. The link will be similar to https://<branch>--<repo>--<owner>.hlx.page

Congratulations! You now have a fully working and styled quote block. You can use this example as a basis for designing your own project-specific blocks.

Block Options block-options

If you need a block to look or behave slightly differently based on certain circumstances, but not different enough to become a new block in itself, you can let authors choose from block options.

By adding a classes property to the block, the property rendered in the table header for simple blocks, or as value list for items in a container block.

{
  "id": "simpleMarquee",
  "fields": [
    {
      "component": "text",
      "valueType": "string",
      "name": "marqueeText",
      "value": "",
      "label": "Marquee text",
      "description": "The text you want shown in your marquee"
    },
    {
      "component": "select",
      "name": "classes",
      "value": "",
      "label": "Background Color",
      "description": "The marquee background color",
      "valueType": "string",
      "options": [
        {
          "name": "Red",
          "value": "bg-red"
        },
        {
          "name": "Green",
          "value": "bg-green"
        },
        {
          "name": "Blue",
          "value": "bg-blue"
        }
      ]
    }
  ]
}

Using Other Working Branches other-branches

This guide had you commit directly to the main branch for simplicity’s sake. For experimentation in a sample repository, this is usually not an issue. For actual project work, you should follow development best practices by developing on a different branch and reviewing all changes via pull request before merging to main.

When you are not developing on the main branch, you can append ?ref=<branch> in the Universal Editor location bar to load the page from your branch. <branch> is the branch name as it would be used for your project’s preview or live URLs, e.g. https://<branch>--<repo>--<owner>.hlx.page.

Publishing content with a new model is only supported when the model is merged to the main branch.

Reusing Your Blocks for Document-Based Authoring reusing-blocks

You can use the blocks you create for WYSIWYG authoring using the Universal Editor for document-based authoring if you adhere to the same content model.

Please see the document Blocks for WYSIWYG and Document-Based Authoring for more information.

Next Steps next-steps

Now that you know how to create blocks, it is essential to understand how to model content in a semantic way to achieve a lean developer experience.

Please see the document Content Modeling for WYSIWYG authoring with Edge Delivery Services Projects to learn how content modeling works for WYSIWYG authoring with Edge Delivery Services projects.