Building templates in Bolt

To render HTML pages with dynamic content, Bolt uses the Twig templating language. This means that everybody who is familiar with Twig can easily get started with building templates in Bolt.

In short, Twig can be described as a ‘flexible, fast, and secure template engine for PHP.’ Primarily, it separates the markup of your templates from the PHP code in the CMS. It does this elegantly and quickly, which means that writing your HTML templates in Twig will give you clean and legible templates. That means you don’t have to use PHP-like statements in your markup, so there’s less code like this:

 <?php if ( the_something('3') ) { ?>
<h1>Title is: <?php echo the_title() ?>.</h1> <?php } ?> 

And more like this:

    {% if something('3') %}
        <h1>Title is: {{ title }}.</h1>
    {% endif %}

A template in Bolt can use all of the standard Twig tags, with a few additions that are specific to working with Bolt. If you’re not familiar with Twig yet, you should read “Twig for Template Designers”, on the official Twig website.

File Structure

A Bolt website theme consists of a set of twig templates, that are located in the view-folder in the root of your site. You can always add more templates, if you want to. By default, the index.twig template is the homepage, but you can override it using the configuration settings.

The current default theme contains the following files and folders:

The filenames of the ‘helper’ templates all start with an underscore. This is just a convention, to make it easier to recognize which template does what. If one of your contenttypes have a ‘template select’ field, Bolt will skip these helper templates by default.

Tip: the default template set uses includes to insert the header, footer and such, but you’re free to use Template Inheritance if you prefer.

By default, Bolt creates links to single pages based on the contenttypes, and it uses a template based on its name. For instance, if your site has a contenttype foos, a single record in that contenttype will be available under, where slug-of-record is the sluggified version of the title. Bolt will try to use foo.twig as the template to render the page. You can change this by either defining another template in contenttypes.yml, or using a ‘template select’ field in the contenttype. More information about this can be found in the chapter Working with Content and Content types.

Template tags

A simple entry.twig template could look something like the example you see below. Using this example we’ll go over some of the details of the Twig Template language. As mentioned before: Much, much more detailed info can be found at Twig for Template Designers on the official Twig site.

{% include '_header.twig' %}


    <h1><a href="{{ content|link }}">{{ content.title }}</a></h1>

    {# Only display the image, if there's an actual image to display #}
    {% if content.image!="" %}
        <div class='imageholder-wide'>
            <img src="{{ content.image|thumbnail(320, 240) }}">
    {% endif %}

    {{ content.body|raw }}

    <p class="meta">
        Posted by {{ content.username }} on
        {{ content.datecreated|date("M d, ’y")}}

{% include '_footer.twig' %}

What happens in this example is the following:

Twig basics

There are basically three different types of Twig tags that you can use in your templates:

Inside these tags you can use expressions, statements, variables, functions and filters. We’ll give some quick examples here, but for in-depth coverage you should read the Twig manual.

Strict variables

Bolt sets ‘strict_variables’ in Twig to false by default. This will mean you will get not warnings if you try to use a variable that doesn’t exist. This makes it easier to use conditional outputting, because it will allow you to do the following, regardless if content or content.image exist in the current page.

    {% if content.image != "" %}
        (do something with the image..)
    {% endif %}

It will also make sure the following will not give an error in your templates:

    Non existing variable {{ foobar }}, with
    non existing element {{ foobar.pompidom }}.

While this facilitates writing generic templates, it also makes debugging harder, because no error will be shown if you make a typo in a variablename, or try to access a non-existing element. To enable strict variables, set the following in your config.yml:

strict_variables: true

If you do this, you will have to do more strict checking on your variables, because an error will be output, if you try to use a non-existing variable:

    {% if content.image is defined and content.image != "" %}
        (do something with the image..)
    {% endif %}

Are you missing something in the Bolt documentation? If so, please let us know, and we'll fix it.

Fork me on GitHub