ContentBlocks ContentBlocks 2.x Getting Started Quick Start

This walkthrough creates a minimal text block and full-width layout to get you comfortable with how configuration works.

Table of Contents

1. Set the config directory

In System → System Settings, set contentblocks.config_directories to your definitions folder. A portable value:

{core_path}components/contentblocks/config

Or point to a custom path outside the package (recommended for site-specific definitions). See Config Directories.

2. Create your first block

Blocks are configured as JSON. They define the meta data, and the inputs that the block is made up from.

If you’re used to ContentBlocks 1.x, think of a block as a single-row repeater. It is a collection of inputs, which are specific types of content (text, image, link, etc) that get combined into a single template.

Create blocks/text.json describing a simple text field in JSON:

{
    "title": "Text",
    "description": "Add simple text content.",
    "icon": "paragraph",
    "category": "Content",
    "inputs": {
        "text": {
            "type": "text",
            "width": 100,
            "properties": {}
        }
    }
}

Templates are stored alongside the definition files, with the same name, but just a different extension.

Default parsers include support for .twig or .tpl templates. We recommend Twig templates for their flexibility and performance. You can also use .tpl templates to use standard MODX syntax.

You can mix templates of different types in your configuration. If multiples exist, Twig takes precedence.

Create blocks/text.twig:

<div class="text-block">{{ text.value }}</div>

Important to note about Twig is that values will be automatically html-escaped. If a value is expected (and trusted!) to contain html you want to render, you can apply the raw filter: {{ text.value|raw }}.

3. Create your first layout

Create layouts/full-width.json defining the metadata of your layout and the columns it contains.

{
    "title": "Full width",
    "text": "Single column layout",
    "category": "Columns",
    "columns": [{
        "key": "main",
        "title": "Main",
        "width": 100
    }]
}

Just like blocks, layouts also have a separate template file with either a .twig or .tpl extension.

Create layouts/full-width.twig:

<div class="layout-full-width">{{ main }}</div>

For layouts, it’s unnecessary to apply the raw filter; when rendering columns ContentBlocks already marks those as safe HTMl.

4. Configure the canvas (optional)

The canvas is a new concept in ContentBlocks 2. The basic concept is that it separates ContentBlocks from the resource content, opening up a path forward for ContentBlocks to be used in more places than just the resource content.

In the canvas configuration, you can also apply global plugins to the canvas. This is useful for plugins that you want to apply to all layouts or blocks. For example, the HighlightChanged plugin that highlights blocks that have been changed since the last save, or the Fullscreen plugin that adds a button to take a single block or layout fullscreen.

Create canvas/modresource.content.json like this:

{
    "plugins": {
        "HighlightChanged": {},
        "Fullscreen": {
            "blocks": true,
            "layouts": true
        }
    }
}

See Canvas Configuration for more.

5. Show the output in your template

ContentBlocks stores HTML in the resource content. Having [[*content]] in your template is all you need to render that output on the front end.

ContentBlocks does not require any particular library, design system, or other styles or scripts to function.

6. Edit a resource

Open a resource in the manager. Add your layout, then add your Text block to a column. Save the resource. The front-end output is generated from your Twig template when the resource is saved.

Congrats on your first ContentBlocks 2 canvas!

Next steps