Sulu’s Blocks approach supports atomic design principles

The Problem

When editors enter content into a CMS, they want the freedom to compose pages and articles in a way that supports the goal they’re trying to achieve. However, developers need content to be available in discrete chunks that they can adapt to the context. For example, sometimes people ask us how to insert an image using the WYSIWYG editor in Sulu, but this is contrary to our structured-content approach. Inserting images using the editor means they are not single-sourced. This makes it difficult, for example, for a developer to resize images for different devices or make a gallery out of all the images in an article. Another use case is outputting content in a different format, such as XML or JSON, or via API in a headless setup. Templates — which semantically separates every field an editor needs for a particular layout — are one solution to this problem. But as we’ll see, you have to create a new Template for every minor variation. As a result, your editor interface can quickly become confusing and overgrown with too many fields or templates.

Blocks are Sulu’s solution to this problem.

What are Blocks?

Blocks are collections of fields, known as “content types” in Sulu. You can group together any content types you want for a particular purpose. Editors can then add a block to a page and all the pre-specified fields are available for them to fill out.

The best way to understand this is to try it out yourself on our demo website, Sulu.rocks.

Click Sulu-Admin at the top-right, and log in to the backend with the pre-filled password.
On the left menu, click “Articles”.
At the top of the screen, click the “Add” button to add a new article. You will see that the form is empty apart from fields for title, resource locator, and image.
At the bottom of the screen, click “Add block”. The drop-down list at the top of the block shows that you can add text, a quote, a link, and more by changing the block type. With each block type, you have a collection of fields (content types) that are always the same. The “Text” block type is a collection of standard text content types such as title and description, and includes a WYSIWYG editing interface. If you need another paragraph, just add another “Text” block. Notice that there’s a media selection at the bottom of the block. Here, you can select an existing image or upload a new one, and determine its position relative to the paragraph.

The editor can’t break this by resizing the image or editing the HTML, but still has plenty of freedom to style the content.

The form for adding an article on Sulu.rocks — editors can add as many standardized blocks as they like without breaking anything.

The “Quote” block has different content types — the quote itself and the reference to attribute it — and the presentation is taken care of by the system.

As a developer, you can define blocks yourself by configuring them in the XML for the page’s template, which is covered in more detail later in this guide. To reuse block types across templates, block definitions should be stored in individual XML files and imported into the XML template. As well as these XML definitions, the frontend needs to know how to display them, which requires a Twig template.

By popular community demand, we added the Nested Blocks feature. This is useful when you have a block and want to let your editors decide how many items to put inside. A great example is a product feature overview: the developer can define a block “Product Showcase” as a wrapper for the block type “Product Feature.” Editors can then add as many blocks of the type “Product Feature” to this outer block as they want. The developer can limit the maximum and minimum number of blocks on any nesting level.

Use Blocks to reduce the number of Templates so you have less code to maintain and a tidier backend

Templates are similar to blocks in that they provide standard form elements for an editor to fill in. In theory, everything Blocks can do, Templates can do too. Templates are useful if the content structure varies a lot, or different behavior is required. But as soon as you have a similar page structure with small variations — such as text and images in a different order — you either have to limit editors’ options or offer them an overwhelming array of templates. With Blocks, you get the best of both worlds: a template saves time by defining the overall structure, and Blocks offer the flexibility editors need to adapt the details.

Developers benefit from Blocks too. Not only can large numbers of similar but non-identical templates overwhelm editors, but developers have to maintain them. That can be a lot of code!

Freeing up editors can also reduce the burden on developers as they get fewer support enquiries and requests for new templates. However, this can require more work upfront because it requires a smart templating strategy. It’s also more complicated to abstract requirements out into flexible, configurable blocks and to make sure they are robust enough to work in every edge case.

When you need Blocks – and how they differ from Snippets

Pretty much every project needs Blocks. The only exception is when you barely use content management functionality and instead use the Sulu administration interface to manage custom business objects.

Inserting images: A basic, but widely used, use case for Blocks is inserting images into text without embedding them inline in the text editor.
Feature overview: Here, you would use nested Blocks to allow the editor to add a “feature overview” Block, and then add each individual features as a Block. This is a great example of nested Blocks.

Some people are unsure when to use Snippets and when to use Blocks. Snippets are for reusing content; Blocks are for reusing schema. So if an editor changes the content of a Snippet, the change is reflected everywhere on the website that uses this snippet appears; whereas the same content types are available in every Block, but any changes in content affect only the specific instance. Snippets are ideal for text content that is repeated on more than one page, needs to be uniform across the website, and needs to be amendable by an editor. For example, a specific sidebar or a footer area such as “Social Links”. Although we could use a Block for this scenario, the sidebar would only be available on pages that use templates that offer this Block. A Snippet can be used anywhere.

If you have an existing Sulu website, or are moving from another CMS, you might have many templates that are similar but have some small differences. For example, a template for different departments to create their team page, with different numbers of people or a slightly different order of content. Consider using Blocks instead: it’s much more intuitive for an editor to select a template called “Team” and then choose from the available blocks.

Getting started

Start by looking at your design or existing website and asking yourself where every bit of content comes from. Break the layout down into reusable Blocks and components instead of templates — thinking in templates can lead to too many templates and redundant Blocks.

This diagram shows a wireframe, the XML implementation of a template, the admin form for entering the content, a Twig template that outputs this data, and the frontend output.

Remember that Blocks can have variations too, so you can reduce complexity for the editor by making them configurable. The trick is to strike a balance between reducing the number of Blocks without making individual Blocks so configurable that they are too complex for the editor to understand.

Think about what restrictions you need to put on editors. For example, you may need to limit the number of Blocks within nested Blocks. You’ll need to make sure your frontend testing includes these parameters (four Blocks might be okay, but does the design still work for 19?).

We’re here to help you get it right

Do you need help planning your project? Get in touch and we can fast-track you to success with our workshops as well as consulting and coding services.

How to set up a Block — developer example

In this section, we’ll show you how a developer sets up a Block with some code examples to get you started. However, for full instructions, check out the Blocks docs.

In this example, we’re going to take two simple Block definitions: one is a Block with only a text editor content type, and the other is just a media selection. This simple setup illustrates how the separation of text from images can be achieved while giving editors maximum flexibility.

There are two major steps to defining a Block:

Define the Block in XML. This tells Sulu which content types the Block contains and how the data entry form is displayed in the administration interface. This is stored in the XML template, but in a well-organized project Block definitions are reused by storing them in separate files and importing them where they are needed.
Create the Twig code that determines how the Block is displayed on the public website (unless you’re running an entirely headless setup without using Twig to output to json).

Developers usually use pre-existing skeleton code and then make a few tweaks. Sulu keeps this configuration in code, which is much more manageable and maintainable than configuring it through the administration interface, and also has the benefit of completely separating configuration from content — one of Sulu’s major USPs.

<block name="blocks" default-type="text" minOccurs="0">
    <meta>
        <title lang="en">Content</title>
        <title lang="de">Inhalt</title>
    </meta>
    <types>
        <type name="text">
            <meta>
                <title lang="en">Text</title>
                <title lang="de">Text</title>
            </meta>
            <properties>
                <property name="title" type="text_line">
                    <meta>
                        <title lang="en">Title</title>
                        <title lang="de">Titel</title>
                    </meta>
                </property>
                <property name="description" type="text_editor">
                    <meta>
                        <title lang="en">Description</title>
                        <title lang="de">Beschreibung</title>
                    </meta>
                </property>
            </properties>
        </type>
        <type name="gallery">
            <meta>
                <title lang="en">Gallery</title>
                <title lang="en">Gallery</title>
            </meta>
            <properties>
                <property name="title" type="text_line">
                    <meta>
                        <title lang="en">Title</title>
                        <title lang="de">Titel</title>
                    </meta>
                </property>
                <property name="images" type="media_selection">
                    <meta>
                        <title lang="en">Images</title>
                        <title lang="en">Bilder</title>
                    </meta>
                    <params>
                        <param name="types" value="image"/>
                    </params>
                </property>
            </properties>
        </type>
    </types>
</block>

Create the XML Block definition

In the above example, even if you’re unfamiliar with XML you might be able to see where the most important settings such as Block type and title — the label displayed in the administration interface — are added and appreciate that this is straightforward for a developer.

{% for block in content.blocks %}
    <section>
        {% if block.type == 'text' %}
            <h2>{{ block.title }}</h2>
            {{ block.description|raw }}
        {% elseif block.type == 'gallery' %}
            <h2>{{ block.title }}</h2>
            <div class="gallery">
                {% for image in block.images %}
                    <img src="{{ image.thumbnails['sulu-260x'] }}" alt="{{ image.title }}"/>
                {% endfor %}
            </div>
        {% endif %}
    </section>
{% endfor %}

Create the Twig template

This simple example takes each Block and checks whether it’s of the type “text” or “gallery” and then outputs it accordingly.

Advanced features

Sulu has advanced content-management features so that you can tailor content to your users. These features unleash their full potential when Blocks are used:

Segments: You can set up different segments for your website, and specify which segment(s) a Block should be displayed for. For example, use segments to create a winter and summer version of your website. Visitors will see a default view then might use a switcher to choose a different version of content. This is a core feature since Sulu 2.2. Find out more in the documentation for Segments.
Audience targeting: This is slightly different from Segments. When visitors view a URL on your website, if they are in different target groups they will see adapted content. Editors can use the administration interface to add and configure rules that determine which group a visitor is in. You need to install the AudienceTargetingBundle to use this functionality. See the AudienceTargetingBundle documentation for more information.
Block display settings: From Sulu 2.2, editors can assign a Block to segments and target groups, and specify whether it should be displayed on the public-facing website or not.

See the Blocks docs for detailed information

In this guide, we’ve given you a grounding in how Blocks work, and given you some food for thought when planning a website with Sulu. If you’re a developer looking to take the next steps, your next port of call should be the Blocks docs for further details and tutorials.

We’d love to see you in our Slack channel too, where you can ask the community for help when you get stuck. If you’re not already in there, find out how to sign up.

Understand Blocks for structured content and slick editor experience