The WordPress Twenty Twelve and Twenty Thirteen themes use identical ways to display entries inside the loop. Instead of calling
the_content directly from among others index.php and single.php, they include a file for displaying the entry based on the post format using get_template_part combined with get_post_format.
Using this method, the themes handle the displaying of post entries via a single file (in this case, one file per post format), allowing the developer to easily change the outputted content for entries: instead of changing index.php, single.php, archive.php and all other files where a post entry is outputted, the developer can just change the appropriate template part file for the post format and alter the output on all pages where the template part is used.
So that’s one type of recurring content, and one way to handle it…
Besides post entries, every theme has more types of recurring content. There’s pagination, breadcrumbs, post navigation, not to forget sidebars, headers and footers. For the latter three, WordPress already has built-in functions:
get_footer. For the other types of recurring content, however, it might not be so clear which approach is the right one.
Let’s talk about the different aspects of recurring content, illustrating approaches and their pros and cons by taking a look at the Twenty Thirtheen theme.
The Twenty Thirteen theme makes use of post formats a lot; it features five to ten post formats and it has separate output for each of them. For displaying post content, it uses
get_template_part. The reason for this partly lies in the use of post formats: it tries to display the entry from the template that was specifically made for the post format used, and falls back to the generic post entry template otherwise.
To refresh your memory: this is the order in which WordPress looks up the theme file for a call to
get_template_part( 'content', $post_format ):
So, when the post format is image and there is no file named content-image.php in both the child and the parent theme, it will load the file content.php in the child theme (assuming that file exists): it’s using the template part without the specialization suffix. This allows for a nice hierarchy in display behaviour of a theme.
Abstracting functionality from structure
Another way of handling recurring content is by using functions. WordPress does this all the time:
the_content and all the other loop functions are just the tip of the iceberg as far as WordPress functions for displaying recurring content go.
For these functions, used inside the loop, the reason for choosing to use them over, say, directly accessing the post object are obvious: they separate the underlying WordPress structure from your application and allow for the automatic application of filters (without having to call
apply_filters or a similar function yourself) to the requested content.
Now the Twenty Thirteen theme also features pagination. For this part of the theme, it uses a function (
twentythirteen_paging_nav) instead of a template part. So why is this?
Using functions to get template parts
Wait… what? Aren’t we confusing and randomly combining the two methods described above? No, we’re not. I’m talking about the native WordPress functions
These functions have behaviour very similar to
get_template_part, as they just include a theme file with an optional specialization (if you didn’t know yet: each of these three functions has a parameter
$name which causes the sidebar function to load sidebar-
$name.php instead of sidebar.php (the other two functions behave alike). However, there’s one big difference: these built-in functions don’t support the fallback template. When calling
get_header( 'home' ), WordPress will not fall back to the themes header.php if header-home.php doesn’t exist, but to the compatability themes header.php file — which has been deprecated since WordPress 3.0.
But as is clear,
get_footer are the same type of function as
get_template_part: they include a template file.
Template parts vs. functions
Even though the distiction between template parts and functions may seem vague when deciding what approach you should use, it’s actually quite clear in most cases. In my opinion, template files are supposed to be used for displaying main, recurring parts of the page: content sections.
Template files should be used for outputting recurring aggregated content that can be seen as main sections in your website. They’re not suited for only outputting data such as a post title, they need to contribute to the structure of the page. This becomes clear in using them to display the header, sidebar, footer, comments section or post entry.
Something that template parts are not suited for, however, is any form of functionality (please note that main functionality doesn’t belong in your theme at all, I’m talking about theme-specific functionality). The only conditional statements that should appear in a template part are the ones that check for the existence or non-emptiness of a value, and the ones that run comparisons (which is actually what checking for non-emptiness does as well).
When you do need to incorporate any form of logic or functionality other than the forms described above, you should use a function. You should also use a function when the output you intend to generate is not a main part of the page structure. Examples of output that have this last property are pagination, menus (as these are almost always part of a template part) and social sharing buttons for your articles.
Let me try to provide you with a few simple rules for deciding whether to use template parts or function calls… Here goes:
Use functions when:
- You need to incorporate logic in your recurring content
- Your recurring content is not a main section of your page
- The content you’re outputting is more about data (e.g. post data) than structure (HTML)
Otherwise, use template parts.
Now, I’m sure there are exceptions — and I would be glad to hear all about them in the comments section — but these should be guidelines covering the vast majority of instances of recurring content you’ll be facing during development.
It might be possible to more clearly define the borders of functions and template parts using the semantic structure of HTML5 — provided that your theme is HTML5, of course. However, that’s out of the scope of this article. Maybe some other time!
When using template parts, please either prefix them or put them in a subfolder. This way, it’s much easier to make the distinction between template parts and other theme files, which eliminates quite a few annoyances and quite some confusion.