Timber + ACF for the Win

Posted January 19, 2015 in Projects, WordPress

I’m excited to officially announce the launch of It was really fun to build, thanks to my new favorite pair of things in the world: Timber with Advanced Custom Fields. I’d like to share some highlights of my process, and maybe even convince you to try out Timber on your next project.


Timber: Twig + WordPress

Timber is a library for WordPress that allows you to separate template logic from presentation with object-oriented templates with the Twig PHP template engine (very similar to Django templating). A quick example from Timber’s docs:

// Ew PHP

$thumb_id = get_post_thumbnail_id($post->ID); 
$url = wp_get_attachment_url($thumb_id);  ?>

<img src="<?php echo $url; ?>" alt="Thumbnail for <?php echo $post->post_title; ?>" />
{# Wow, wow, Timber #}

<img src="{{post.thumbnail.src}}" alt="Thumbnail for Timber" />

I can’t speak for everyone, but the WordPress loop drives me a little crazy sometimes. Mixing PHP logic and variable definitions with my template markup is really distracting, and I hate worrying about opening, closing, and resetting the loop. I’ve had some experience working in Django and Rails projects where templating was a breeze: I didn’t have to worry about getting or defining data within my markup, all of that happens in a separate part of the application. The data is managed and passed to the template (a.k.a. the view) from a different part of the application (a.k.a. controller), so that in my HTML I can focus on just that, my HTML. In Timber, the data management happens in the regular WordPress PHP theme files, and the markup in a corresponding Twig template.

A good example is printing a list of tags or other terms the standard WordPress way. To be totally honest, I had to look this up every single time I needed it, and there are always a million ways! With Timber though, there’s on way, simple and readable:

<ul class="list-terms">
{% for term in post.terms('tags') %}
    <li class="term-item"><a href="{{}}">{{}}</a></li>
{% endfor %}

Let’s say you have a custom taxonomy, all you would do is replace the 'tags' argument with 'your_taxonomy'. All of the data in the post object has been made available for you in the WordPress PHP template as part of the TimberPost object, which is taken care of in the included Timber starter theme. Read more about how that works in the docs here.

Printing this list in regular WordPress could look something like this:

<?php $terms = get_the_term_list( $post->ID, 'my_tax', '<li class="term-item">', ',</li><li class="term-item">', '</li>' ); ?>

<ul class="list-terms">
    <?php echo $terms; ?>

Ok, there are definitely cleaner ways to do it. But that’s the problem: there are 10,000 ways to choose from! And it drives me nuts. Seriously, Google “print custom taxonomy list wordpress” and you’ll see how many different solutions there are. Right off the bat I see get_taxnomies(), wp_list_categories(), and get_terms().

The only caveat to Timber is that if you aren’t familiar with object oriented concepts or MVC frameworks, it’s takes a little time to get the hang of the mentality. It’s a different way of thinking about your site development, but believe you me, it’s worth it. The docs are excellent, it’s well supported and the ultimate time/headache savings is huge in the long run.

Next up:

Advanced Custom Fields

The MTNmeister site is composed entirely of custom fields, and truly uses WordPress as a CMS. Here’s an example:

A simple text repeater field, see it at the bottom of a Meister page.

And guess what? Timber gets even better. It has built in tools for working specifically with Advanced Custom Fields, and again, is very well documented. Here’s the code for the custom fields above:

{% if post.additional_resources %}
     <section class="article-section container-squish">
          <header class="article-section-header">
               <h3>Additional Resources</h3>
               <p>Check out these links to additional episode content.</p>

          <ul class="list list-table">
               {% for item in post.get_field('additional_resources') %}
                    <li><a href="{{item.resource_link}}" target="blank">{{item.resource_title}}</a><span class="meta">{% if item.resource_time_in_episode %} - {{item.resource_time_in_episode}}</span>{% endif %}</li>
               {% endfor %}
{% endif %}

Where resource_link in {{item.resource_link}} is the name of the field.


Bye bye, WYSIWYG

I had recently read Karen McGrane’s Content Strategy for Mobile, and the concept of separating content and presentation makes a ton of sense. Content creators shouldn’t have to rely on the “Preview” button to know what their content will look like, they should be able to focus on the content itself and never have to muck around in the markup to get the proper display. I am certainly guilty of a <br> or two in this post…let’s leave it at that.

Here’s the Meister custom post type, for example. The only responsibility of the author is to fill in the fields, and to follow the guide for each field.

Click to see a detailed pic, and see Faith Dickey’s page here.

Ah, there is so much more I could talk about! But I want to save it for another post. If you want a sneak peek, I just launched a redesign of where I used a similar, and more refined process. It’s on GitHub here, and I’ll be documenting that one later for sure.