Rendering Pages with Twig

Twig is an awesome option for rendering HTML. It got some nice features like blocks and inheritance. That’s why we use and love Twig.

Build the HTML template

We recommend to build the HTML templates in a first draft with plain HTML and some dummy texts. That means absolutely no placeholders for template engines. This ensures that your HTML is working across all browsers (at least if you test it correctly), and it is easier to test, since there are guaranteed no errors caused by the some wrong template variables.

Please make also sure that your HTML is valid, and use HTML tags in a semantic way, so that your website will achieve the best results in terms of search engine optimization.

Which Twig-Template is used?

In Creating a Page Template we learned how to define a template.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<?xml version="1.0" ?>
<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>default</key>

    <view>ClientWebsiteBundle:templates:default</view>
    <controller>SuluWebsiteBundle:Default:index</controller>
    ...
</template>

In the page template the view could be set. Internally Sulu appends the format of the request to find the correct template to render the response. As an example sulu uses for a html request the template ClientWebsiteBundle:templates:default.html.twig or ClientWebsiteBundle:templates:default.xml.twig for a xml request. With this feature you are able to define different output format for a single page.

Rendering the Content

If you don’t use your custom controller and modify the output the Sulu Controller renders, Sulu passes some default variables to Twig.

Content

In the content everything you defined in your template is saved. If you got a title you could easily obtain it from the content-var.

<h1>{{ content.title }}</h1>

Extension

In the extension var Sulu writes content from Sulu extensions. Typically stuff that is defined in separate Tabs in the Sulu content section. At the moment there is the SEO and the excerpt extension, that could be used. This extensions are available on every page no matter which template you chose.

Here is an example how it could look like in the backend. Notice the Excerpt & Categories tab next to the SEO tab.

../_images/admin-extension-seo.png

You could include the SEO meta tags like this:

{{ sulu_seo(extension, content) }}

The excerpt is available in:

{{ extension.excerpt }}

Images

If there are images defined in your template you could render them by using this code:

1
2
3
4
5
6
{% for image in content.images %}
<div>
    <img src="{{ image.thumbnails['200x100'] }}" alt="{{ image.name }}"/>
    <p>{{ image.title }}</p>
</div>
{% endfor %}

Image formats need to be defined in the image_formats.xml in your config.

More examples

You could find more examples of how content could be accessed in our example file.

Default Template

Just have a look at our default theme, that ships with our standard installation as long with our default page templates over at github.