Better Partial Templates in WordPress

In 2010, WordPress developers added get_template_part to make it easier for theme authors to break their themes into small, reusable partial templates. Instead of copy & pasting the template for a blog title + excerpt, you could create one template that’s used on index.php, archive.php, search.php, etc. This promotes code re-use, which makes debugging easier and development faster.

While get_template_part is undeniably useful, it has some shortcomings that become apparent when trying to build a modular theme:

1. Templates only inherit global variables

Only variables declared globally or variables declared inside a partial template are accessible. Since declaring arbitrary globals can lead to buggier code, this won’t work for us.

2. Encourages coupling templates and data

As a side effect of #1, any additional data that needs to be queried from the database has to be queried within our template, coupling that template to a specific kind of data.

3. Templates automatically echo

Similar to functions like the_title, get_template_part automatically echoes its output. This saves some typing but isn’t always ideal. On some of our client sites, we ran into situations where we wanted to use a partial template within a theme but also in a shortcode. There’s no obvious & easy way to return that template to add_shortcode without adding a bunch of PHP output buffering code.

Introducing silencio_partial

As a front-end developer that works with custom development frameworks often, I found myself wanting templating in WordPress that works like include in Laravel and render in Ruby on Rails. These tools are used to declare variables within your partial templates that are expected to be set by whatever template calls them. This decouples your templates from your data, and makes it easy to share templates across different but similar contexts.

Our WordPress implementation is similar: just call silencio_partial and pass in the name of your partial template and an array of variables. For example:

$foo_from_database = get_post_meta($post->ID, 'foo', true); silencio_partial('page-header', ['foo' => $foo_from_database]);

This makes the output of get_post_meta available as $foo in your partial template, and echoes the template. If we want to just return the template as a string, there’s an optional third argument that when set to false disables echoing. This is similar to some built-in functions that can either automatically echo or return.

To make use of this helper, just drop it into your functions.php file. You can switch the prefix to anything you’d like. We use silencio_ since it’s part of our Silencio starter theme, but there’s no reason you have to.

In Practice

For example, you might build a partial template for a callout that’s populated by a post title & excerpt in some places, but also make it available within WordPress content as a shortcode. With get_template_part you’d be out of luck, and wind up having to code your template in two places.

With our helper, it’s as simple as defining a template, then calling and returning it within your custom shortcode definition.

Here’s an example of a template shared between a page template and a shortcode:

Go modular!

Now that we have this helper set up, you can modularize your theme in ways that weren’t possible before. Have some navigation UI that needs to be populated with child pages on one template and blog categories in another? Figure out what both use cases have in common (ex. a title and a URL) build your template around them, and use it on both pages. Use the same callout template in a shortcode and a custom widget.

If you’re finding this useful or have any improvements, have a look at other features of Silencio or check out the code on GitHub.