Block lists and their types are defined in the template. Global blocks live in config/templates/blocks/ and are offered with <type ref="..."/>. Includes pull fields and sections from other files. Atoms are a convention of the example website: one file, one field.
Series 5: Sulu for developers Chapter 4 of 16
Blocks, global blocks, includes and atoms
In short
Pages and articles consist of blocks. So that nothing is maintained twice, the example website separates blocks into global files and builds their fields from small include files. This chapter explains how that works and which terms come from Sulu and which from the project.
Helpful first: 5.3 Page templates: XML and Twig
A block list
A block list is a field in which editors create blocks of a given type as often as they like, one after another. In the template this is the element <block> with its types. The block “Screen explained” has such a list for its legend:
<block name="legend" default-type="item">
<meta>
<title lang="de">Legende</title>
<title lang="en">Legend</title>
</meta>
<types>
<type name="item">
<meta>
<title lang="de">Eintrag</title>
<title lang="en">Entry</title>
</meta>
<properties>
<property name="title" type="text_line" colspan="4" mandatory="true">
<meta>
<title lang="de">Kurztitel</title>
<title lang="en">Short title</title>
</meta>
<tag name="sulu.block_preview" priority="2048"/>
</property>
<property name="text" type="text_editor" colspan="8">
<meta>
<title lang="de">Erklärung</title>
<title lang="en">Explanation</title>
</meta>
</property>
</properties>
</type>
</types>
</block>
default-type is the type a new block gets. minOccurs requires a minimum number; the pages of the example website set it to 1. The tag sulu.block_preview marks fields that the admin shows in the collapsed block. The priority (priority) sets the order.
Global blocks
Writing the same blocks anew in every template would mean maintaining them by hand. Sulu has global blocks for this. They live as separate XML files in config/templates/blocks/. The directory is registered in Sulu (SuluCoreExtension), and subfolders are allowed. The example website uses blocks/main for page blocks and blocks/types for article blocks.
In the template you only name the key of the block with <type ref="..."/>. This is the block list of the pages:
<block name="blocks" default-type="main-default" minOccurs="1">
<types>
<type ref="main-default"/>
<type ref="main-media"/>
<type ref="main-accordion"/>
<type ref="main-boxes"/>
<type ref="main-collection"/>
</types>
</block>
The block itself has a <key>, a title and its fields. It gets its fields through an include (next section):
<template xmlns="http://schemas.sulu.io/template/template"
xmlns:xi="http://www.w3.org/2001/XInclude">
<key>main-default</key>
<meta>
<title lang="en">Text</title>
<title lang="de">Text</title>
</meta>
<properties>
<xi:include href="../../includes/sections/header.xml"
xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:template/sulu:properties/*)"/>
</properties>
</template>
The admin inserts the global blocks when it loads the template. Behind this is the tag sulu.global_block (see GlobalBlocksTypedFormMetadataVisitor); you do not write it yourself.
How Twig finds the block
The type name determines the Twig file. Page blocks are called main-<name> and go to blocks/main/<name>.html.twig, article blocks are called types-<name> and go to blocks/types/<name>.html.twig. The mapping is in blocks/blocks.html.twig (block.type[5:] cuts off main-) and in articles/parts/blocks.html.twig (block.type[6:] cuts off types-). If the Twig file for an article block is missing, the list skips the block.
{% extends 'blocks/_base.html.twig' %}
{% block content %}
<div class="row{{ row_class }}">
<div class="col-12">
{% include 'atoms/title.html.twig' with {class_alignment: alignment_header} %}
{% include 'atoms/text.html.twig' with {class_alignment: alignment_content} %}
</div>
</div>
{% endblock %}
In the example website, import and set stand inside a block, not at file level. Otherwise the preview in the admin breaks. This is a project rule of the example website, not a requirement of Sulu.
Includes
With XInclude you pull in parts of another XML file. The path in the attribute href is relative to the file it appears in. The xpointer selects what is included: in the example everything under <properties> of the target file. In this way the file sections/header.xml assembles a section “Header” from fields:
<section name="sections-header">
<meta>
<title lang="en">Header</title>
<title lang="de">Header</title>
</meta>
<properties>
<xi:include href="../atoms/title.xml"
xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:template/sulu:properties/*)"/>
<xi:include href="../atoms/subtitle.xml"
xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:template/sulu:properties/*)"/>
</properties>
</section>
Atoms
“Atom” is not a Sulu term but an order used by the example website. An atom is a file in config/templates/includes/atoms/ with exactly one field. A section in includes/sections/ is a group of such fields, and a block or a template assembles sections.
<template xmlns="http://schemas.sulu.io/template/template">
<properties>
<property name="title" type="text_line">
<meta>
<title lang="en">Title</title>
<title lang="de">Titel</title>
<info_text lang="de">Überschrift.</info_text>
<info_text lang="en">Heading.</info_text>
</meta>
<tag name="sulu.block_preview" priority="2048"/>
<tag name="sulu.search.field" />
</property>
</properties>
</template>
This pays off above all for select fields that appear in several places. The level of a handbook chapter (difficulty.xml) and the audience (audience.xml) are such atoms. Two things apply:
- The ending
.mand.xmlmeans a required field:title.mand.xmlhasmandatory="true",title.xmldoes not. - An atom cannot change its default value. If a template needs a different default or none, it uses its own copy of the file. That is what the comment in
difficulty.xmlsays.
Nothing gets left behind
The test tests/Architecture/NoOrphansTest.php checks that every include file is reached by a template, every block type is offered somewhere and every block Twig has its XML file, and the other way round. More about the tests is in “Tests for templates and Twig”.