Page templates: XML and Twig

Development
Applies to: every Sulu website As of Sulu 3.0

In short

A page template consists of an XML file in config/templates/pages and a Twig file that <view> points to. Twig receives content, view, extension, resource and localizations. You load other pages with sulu_page_load and a list of the properties you want.

A page template consists of two files. The XML file describes the fields for the admin, the Twig file shows the content on the website. The examples come from the templates of the website bertrams-media.

Helpful first: 5.2 Setting up a project and the webspace

The XML file

The template lives in config/templates/pages/. Its file name is free; what matters is the element <key>. Added to that are the Twig file (<view>), the controller, the cache lifetime, a title for the admin and the fields. The template default of the example website includes its fields from page-default.xml and includes/default.xml. Here is a skeleton with just two fields, shortened from page-default.xml:

config/templates/pages/simple.xml, shortened from page-default.xml html
<?xml version="1.0" encoding="utf-8"?>
<template xmlns="http://schemas.sulu.io/template/template"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">

    <key>simple</key>
    <view>pages/simple</view>
    <controller>Sulu\Content\UserInterface\Controller\Website\ContentController::indexAction</controller>
    <cacheLifetime>604800</cacheLifetime>

    <meta>
        <title lang="en">Simple</title>
        <title lang="de">Einfach</title>
    </meta>

    <properties>
        <property name="title" type="text_line" mandatory="true">
            <meta>
                <title lang="en">Title</title>
                <title lang="de">Titel</title>
            </meta>
            <params>
                <param name="headline" value="true"/>
            </params>

            <tag name="sulu.rlp.part"/>
        </property>

        <property name="url" type="route" mandatory="true">
            <meta>
                <title lang="en">Resource Locator</title>
                <title lang="de">Adresse</title>
            </meta>

            <tag name="sulu.rlp"/>
        </property>
    </properties>
</template>
  • <view> is the Twig path without the extension: pages/simple means templates/pages/simple.html.twig. The controller appends .html.twig itself.
  • <controller> is ContentController::indexAction from the package content in all templates of the example website.
  • <cacheLifetime> controls how long the response stays in the HTTP cache. The page templates of the example website use 604800 (seven days), the handbook chapters 2400.
  • The tag sulu.rlp.part on the title tells the admin which fields to suggest the address from. The tag sulu.rlp marks the field that holds the address. Without both there is no suggestion.

The Twig file

The Twig file extends a layout and fills its blocks. In the example website that is layouts/page.html.twig, which brings header, banner, breadcrumbs and footer and offers the block content. At its core, the template default consists of two lines:

templates/pages/simple.html.twig html
{% extends "layouts/page.html.twig" %}

{% block content %}
    <h1>{{ content.title }}</h1>
    {% include 'blocks/blocks.html.twig' with { blocks: content.blocks, view_blocks: view.blocks } %}
{% endblock %}
The example needs a field “blocks”

The second line in the block assumes a block list called blocks in the XML template, as includes/default.xml provides it. How blocks are built is covered in “Blocks, global blocks, includes and atoms”.

What Twig receives

The controller passes the result of the content resolver on to Twig. The structure is documented at the top of ContentResolver::resolve(): resource (the entity), content (your fields), view (additional data parallel to the fields, such as the UUIDs of chosen pages) and extension (excerpt and SEO). In addition there is localizations with address, language and alternate for each language the page exists in.

The blocks therefore come in two lists: content.blocks[i] has the field values, view.blocks[i] the additional data of the same block. The blocks.html.twig of the example website joins both and includes the matching file for each block:

From templates/blocks/blocks.html.twig, shortened html
{% for block in blocks %}
    {% set block = block|merge({'position': loop.index, 'view': view_blocks[loop.index0]}) %}
    {# Block "main-text" -> blocks/main/text.html.twig #}
    {% include 'blocks/main/' ~ block.type[5:] ~ '.html.twig' with block %}
{% endfor %}

Loading pages and navigation

You load other pages with sulu_page_load(uuid, properties, locale). Since Sulu 3 the parameter properties is required and maps output names to paths in the resolver. The result contains the values at the top level, so page.title and not page.content.title.

From templates/components/links/link.html.twig html
{% set page = sulu_page_load(link.href, {
    'title': 'title',
}) %}
{% set title = page.title|default(null) %}

For menus there are sulu_page_navigation_tree, sulu_page_navigation_flat, sulu_page_navigation_root_tree and sulu_page_navigation_root_flat. The footer of the example website uses them to read the navigation context links down to the second level:

From templates/partials/footer/footer.html.twig html
{% set footerNavigation = sulu_page_navigation_root_flat('links', 2, {
    'uuid': 'object.resource.id',
    'title': 'title',
    'url': 'url',
    'webspaceKey': 'object.resource.webspaceKey'
}) %}
Clear the cache after XML changes

The admin reads the fields from the XML file. If you change them, clear the cache of both contexts, otherwise you will still see the old form.

More on this

Official documentation