Building Sane, Reusable WordPress Templates with Timber and Twig

An image of the author with Hulk hands shares the foreground with an illustrated ninja over a backdrop of code
Traditional WordPress templates are written in PHP code that mixes HTML output with more advanced programming logic. The Timber plugin for Wordpress lets you move the markup part of your templates into separate files written in Twig, a simple yet powerful templating language. When you separate logic from layout in this way, your themes will be easier to read, easier to edit, and more portable.

One of the tools I use on a daily basis is a WordPress plugin called Timber. Timber enables a collaborative template-building workflow for WordPress that’s especially helpful for the kind of small dev teams that are common in higher education.

There comes a point in a lot of web projects, especially in higher ed, where some additional developers would be helpful, but the cost of either hiring an experienced WordPress developer or training a less experienced developer is outside of your budget, or would take so long that it would slow your project down even more.

The way that WordPress works can contribute to this problem. Because it keeps its front end HTML and back end PHP mixed together in the same file, every dev you have working on your WordPress templates needs to have a minimum level of understanding of PHP and the WordPress API.

When I first joined NewCity and they said they needed me to develop WordPress templates, I was like “Sure! I’m a front-end developer with no WordPress experience, but templates are just HTML with holes for content, right?”

Then I opened up my first WordPress starter theme. I didn’t even know what I was looking at! Big chunks of PHP mixed together with big blocks of HTML? Echo statements inside of HTML attributes? And this was all normal, well-formed WordPress code — it was just so foreign to me that my first reaction was panic!

Eventually I learned how to read and write code like this, but it took me a while. The cost of training up a front-end developer, like I was, into a WordPress developer is pretty high, and a lot of web teams don’t have the budget for it.

It doesn’t have to be this hard to write the HTML for a WordPress template. If we could separate out that HTML code from the PHP code, front-end experts and WordPress experts could focus on their respective strengths, and we could take advantage of their expertise with less training time. We could quickly add members to our team and get them into productive work right away.

That’s what the Timber plugin does for you. Timber lets you split your templates into two files that I’m calling the “controller file,” written in PHP, and the “view file” that contains the front-end code.

Illustration showing the relationship between 'controller' and 'view' files

The controller file is for experienced WordPress developers. It’s where you get at the full power of PHP and the WordPress API, and also all the risks that come along with that power. The view file is where the actual HTML markup for a given content type is defined. It’s much easier to read than mixed PHP and HTML, and it gets rid of the need for your front-end developers to poke around in potentially dangerous code.

In WordPress terms, the view file is for code editors and the controller file is for code admins.

Let’s take a look at the code contained in these two files, starting with the view file. Timber view files are written in a language called Twig. Twig starts with plain HTML and supplements it with its own markup syntax that’s used to insert values — or even other Twig files — into the HTML document. Here’s a basic example.

Screenshot of twig and HTML code

This code snippet here could be inserted at the top of a Twig template for a WordPress post, where it would pull the post’s title, author, and date and wrap them in the correct HTML markup.

The Timber plugin library is responsible for linking those common WordPress post fields to convenient Twig variables like post.title. There’s a whole list of these variables, and they cover almost any WordPress value you can think of.

The controller file is where you can access PHP functions and the WordPress API directly. The big difference between this controller file and a traditional WordPress PHP template is that instead of echoing the output of function calls directly to the page, with Timber you pass those output values to the view file.

This PHP file can be as simple or as complex as you want depending on your needs. Here’s the simplest possible controller file for a Timber template. This is a “single post” template — every WordPress theme has a version of this. All Timber controller files will contain some version of this code.

In plain English, when a WordPress post is accessed, this code grabs the current post and links a bunch of its fields and attributes to the Twig variable names I mentioned with the view file — post.title and so on. All of those values get wrapped into a bundle called the Timber “context”. That’s the first three lines of code. Then that context bundle gets passed along to a Twig view file for rendering. That’s the last line of PHP there, which in this case says to use a view file called single.twig.

Illustration explaining how twig and PHP code work with Timber to produce a single web page

Pulling back from the code for a moment, here is an overview of how a single field, the post’s title, passes through the Timber template and ends up on a web page. First, the title is stored to the WordPress database from the standard post edit screen as usual. Next, when that post is requested by a browser, the PHP controller file pulls up all of the data for the post and assigns variable names to its values.The controller then passes that data along to the view file, where the post.title variable is replaced with the actual post title from the database. Finally, HTML is generated that WordPress sends to the browser, where the post title is displayed as a Heading-1.

Earlier, I mentioned that the default Timber Twig variables cover “almost any WordPress value you can think of,” but what if you need a value that isn’t included in the defaults? No problem! Using the controller file, a developer can create new variables for any data that WordPress and PHP can generate.

Imagine that you’re a development team at a university with only one full-time WordPress developer. Maybe you have a few part-time or student developers who only know HTML. Maybe you don’t have any yet, but you’re thinking of hiring some.

With Timber, your full-time developer can create the controller files, building out the features that your site needs. At the same time, the student developers can use their HTML skills to build Twig view files that are easy to read and share, and they don’t have to get anywhere near the dangerous backend code that could break your whole site.

As your student devs graduate, their replacements can quickly get up to speed because they only need to know HTML plus a handful of simple loops and conditionals to get started.

That’s the power of separating your templates’ PHP from their HTML. If that sounds like it would be useful for your team or organization, I encourage you to give Timber a try.

This is a basic introduction to Timber. If you’re interested in learning more I’m planning to produce a video series on Timber, so stay tuned. And if you have questions or want to share something cool you’ve done with Timber, email me or send a twitter message to @wonkeythemonkey.

NewCity logo