How and Why Developers Should Adopt a Blocks-First Approach
Sulu’s blocks have a lot of benefits and we recommend you read our guide to understand how they work. In this post, we’re going to give you an overview of what’s important for developers to know. This includes why you should use them, and how to get your head around them. They do take some getting used to if you’ve only ever worked with templates and WYSIWYG editors in the past. Essentially, blocks are the best way to hold content in a structured manner while placing the loosest possible restrictions on editors.
Take a blocks-first approach to reduce the number of Templates
You should use blocks in almost every website project because they strike the balance between flexibility (for editors) and consistency. In fact, it’s probably easier to use blocks by default and only create a different template when you have to. So break down the design, or the website you’re relaunching with Sulu, into blocks first and only create new templates when you run up against the limits of what blocks can deliver. If you notice different but similar content modules, you should aim to reuse a block but add an option for the editor to configure it — this eliminates unnecessary duplication and keeps the interface clean.
To help you understand when to use a new template instead of adapting existing blocks, here are some example situations:
- You think you can save editors time by defining a template for a layout they use very often, so they don’t have to click the blocks together themselves.
- You have a completely different design with a different set of predefined content types.
- You need a specific behavior or functionality.
- You want different templates to make different block types available to editors so the template is less cluttered. For example, a page template might make a Google Maps block available and an article template might contain a list of related articles.
Benefits of blocks for developers
Taking a blocks-first approach is usually beneficial not only for editors but also developers. You might need to put in some more effort at the beginning, but it will pay off in the long run.
- Developers can access content in a structured form so they can do more with it (from responsive images to headless IoT applications).
- There’s less code to maintain if you have fewer templates. You can achieve this by offering different blocks and different configurations so you don’t need a new template for every edge case.
- You might have fewer support requests or requests for new templates, because editors can build a page structure suited to their needs.
- If you do have to fix a bug in a block, you can fix it once and it works everywhere. If you have many templates, you may have to fix and test the issue in many different places.
Define blocks once and reuse them across templates
As outlined in the guide, blocks are defined within template definitions in XML, and in Twig templates. We’re going to show you how we do it on the sulu.rocks website, where we define each block individually so we can reuse them wherever they are needed. This way, we don’t have to maintain various different variants, which could get confusing.
The code for the sulu.rocks demo website is available on Github — instead of duplicating the code for the longer examples, we’ve just linked to it below.
Let’s take a look at the block an editor uses to insert a link to another page within the website.
The Text block has a title field for the headline, one for descriptive text, and a field for selecting an image from the media library.
We put the XML definition for this block in the directory /config/templates/includes/blocks.
Along with the other blocks, we include it in blocks.xml in the parent directory:
<xi:include href="blocks/text.xml"
xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:properties/sulu:block/sulu:types/sulu:type)"/>
We then include blocks.xml itself in the site’s page template called "default", as well as in the templates called “homepage” and “overview”:
<xi:include href="../includes/blocks.xml"
xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:properties/sulu:block)"/>
Finally, the corresponding Twig template defines how this block is displayed in a browser. The directory structure for the website’s templates mirrors that of the admin interface, so you can find the corresponding Twig template under /templates/includes/blocks.
Parallel to the structure for XML templates, this Twig definition is included in blocks.html.twig in the parent directory:
{% for block in content.blocks %}
<div class="blocks__item">
{% include 'includes/blocks/' ~ block.type ~ '.html.twig' with {
content: block,
view: view.blocks[loop.index0],
} only %}
</div>
{% endfor %}
And then all these Blocks are pulled into the Twig template for this site’s page template “Default” in the template definition itself, as well as the other templates in their respective Twig files.
And that’s it! Now you can maintain your block definitions in just two files, instead of having similar definitions distributed across templates.
Check out the guide and Blocks docs or ask questions in Slack
We appreciate that Blocks can take some getting used to, but we believe they are the best way to structure your content. Some people also have difficulty understanding the difference between Snippets and Blocks, and when to use which. Check out the guide, and the documentation, to find answers to your questions, or ask a question in Slack. We and the rest of the community are happy to help.
