How we use Timber

How we use Timber Masthead

Crowd adopted Timber in Wordpress builds at the start of 2016 and it has massively changed the way we approach Wordpress projects. Using Timber does change the file structure of our themes, so we have created a ‘base-build’ that we like to use as our starting point for our projects. The Crowd Base Build is a fork of the Timber Starter Theme with only a handful changes to make it work for Crowd’s preferred approach and our Front-end workflow.

.twig + .php — a separation of concerns

The biggest change that Timber introduces is the use of .twig template files to split out templating from PHP. The idea here is the .php Wordpress files catch and processes data (from the database) and the .twig files render it using twig template syntax.

Folder structure

With all these new files added to our theme’s markup, we like to arrange things to follow a certain folder structure. At the root of the theme, we have any .php files that handle the initial data or theme configuration, such as functions.php and index.php.

Then, the twig files are split into two different directories, templates and components. The templates folder contains standard page templates (e.g. single.twig). Template twig files are the files that construct the different layouts used around the site and are made up of included components.

Each component has it’s own .twig file inside of the components directory. These are self contained bits markup that can be included in the different page templates found in the templates directory.

How we do components

Page templates in Timber aren’t too different from standard Wordpress PHP templates except they use TWIG as a templating language, as opposed to PHP. For ‘fixed’ or standard page templates, we like to write the page’s main structure as usual. Then for the blocks that are re-usable around the site, the ‘components’, we include them using a twig include.

// templates/template-content-page.twig
{% include 'masthead.twig' with { 'masthead': post } %}

This way we can create a component in one file and use it in multiple places. And if the component needs to be changed at all, we need only change it in one place, keeping things quick and easy to maintain. Some examples of components are:

  • A masthead or page header
  • A mailing list signup component
  • A social network sharing component
  • A post type listing component

Of course, with Timber and the way it handles data, a component’s content can be dynamic, so it doesn’t have to be fixed.

Flexible page templates

For projects that require a higher level of customisation, we can include components in page templates dynamically. To do this, we create a component that includes another component based up filename, usually named: flex-content.twig. This component is then included in the page template and passes in the flexible content field setup with Advanced Custom Fields.

// templates/template-hub.twig
{% include 'flex-content.twig' with { 'flex_content' : post.get_field('flex_content') }%}

Then inside of the flex-content.twig component, we loop through all of the flexible content blocks assigned to that page and include their relevant components based upon file name:

// components/flex-content.twig
{% for content_block in flex_content %}
    {% include [
        'content-blocks/content-' ~ content_block.acf_fc_layout ~ '.twig',
        'content-blocks/content-no-template.twig'
    ] with {
        'content' : content_block
    } %}
{% endfor %}

When creating the components for a flexible content loop, such as a above, we like to place all of these components in a sub-folder to keep them all together and we prefix the names with ‘content-’. The filenames of these components need to match the name of the layout in Advanced Custom Fields, so we sometimes have to mix dashes and underscores in filenames, such as: content-rich_text.twig.

Finally, we create a component called ‘content-no-template.twig’ which simply contains an error message:

Sorry, there is no template for this content block.

This is a fallback, in case someone creates a new content block in the back-end, without creating the relevant component template file.

Builds that use Timber

Further Information

For more on Timber and how we’ve learned to use it, check out @matbush’s blog post: Checkered Shirts & Denim – A Year With Timber on The Crowd website.

Be part of the Crowd

We're always on the lookout for talent, and currently have offices in the USA, Canada, UK, Dubai, and China.

If you fancy being a part of a global multicultural development team that strives to do the best work possible, email us at results@thisiscrowd.com