Cancel

Justin Tadlock

Theme Authors Can Pass Data to Template Files in WordPress 5.5

Theme developers can finally rejoice. For the first time, it is now possible to pass data to templates via the various core template-loading functions. Enrico Sorcinelli announced the change on the Make Core blog this past Friday.

The feature was originally proposed by Scott Kingsley Clark in 2012. Over the years, the ticket has received a dozen patches. It has survived a closure and arguments over why the feature should not go into core. Sorcinelli was a primary driver that kept the ticket alive for the last few years.

WordPress developers have been cleaning up some old-but-useful feature requests for the 5.5 release cycle. A couple of weeks ago, an 11-year-old ticket to allow users to update themes and plugins via a ZIP file made the cut. Core developers even closed a 9-year-old ticket related to an Internet Explorer 6 hack — progress. However, for theme authors, one of the most important additions is control over passing data from one template to another.

Typically, in PHP, variables can be passed from file to file because they remain in the same scope. However, that is not the case if the inclusion of the file is taken out of that scope by including the file from inside of a function. The scope is then limited to the function. That is how the template system works in WordPress. This is not necessarily a bad thing. However, it has meant that theme developers have had no built-in method of passing data from one template to the next.

Imagine creating a variable in one template but needing to access that same variable in a sub-template. There is no shortage of methods to accomplish this, but many are inelegant.

“For years, theme developers wishing to pass data to template files have had to use less than ideal workarounds,” wrote Sorcinelli in the announcement. The worst solutions typically involved creating a global variable. Others created custom template-loading functions on top of WordPress’s existing system. The problem with all methods, regardless of which was ideal, was that no standard existed. Each theme would need to build its own solution, and plugins that touched the front end would often have a competing solution.

All of the WordPress template-loading functions now support an additional parameter of $args, which allows theme authors to pass along an associative array of data to the loaded template. The functions that support this new parameter are:

  • get_header()
  • get_footer()
  • get_sidebar()
  • get_template_part()
  • locate_template()
  • load_template()

Any hooks associated with the functions also pass along the data.

The get_search_form() function has supported a similar parameter since WordPress 5.2. In practice, it should work mostly the same, but the function has a couple of default values it sets.

An additional benefit of having a standard method of passing data to templates is that the feature can be built upon in the future. For example, WordPress could eventually offer a hook for filtering the data, which could come in handy with child themes.

The WordPress template system still lacks the robustness of more modern frameworks, but this simple change will allow for a variety of applications.

One question remains: is the arrival of this feature too late? With WordPress on track to revamp the entire theme system to integrate with the upcoming full-site editing feature, will this feature be useful for only the next few months?

Even if most theme developers don’t immediately jump on board the block-based themes bandwagon for another year, the feature could come in handy until they do. Perhaps it will also have some usefulness beyond the current theming paradigm.

Developers still do not have a clear picture of what theming with blocks will look like in the next few years. There may be situations where passing dynamic data is still necessary in the next system. Even if not, it will likely be a long while before there is mass adoption of block-based themes from the existing theme development community. In the meantime, many will be able to drop in-house solutions and use standard functions.

Category: ,
20

20 responses to “Theme Authors Can Pass Data to Template Files in WordPress 5.5”

    • Templating-related features have largely taken a backseat in WordPress for years. Even the addition of get_template_part(), one of the biggest features over the last several years, was just a wrapper function for existing functionality. Not much has changed, and theme authors have been left to their own devices.

      Often, tickets like this just need someone to champion them. Many of the people with the resources to make improvements to the templating system just stick to building things in-house. They see 8-year-old tickets like this and don’t think it’s worth their time trying to get in core. So, until someone comes along to really push something and get approval, it just sits there untouched.

      Create forum topic from comment

  3. I think things like these are great for the community. While I had a function I always used, when its part of the core, it gets used more, leading to better code overall. It’s crazy it hasn’t been integrated sooner, it’s such a simple change and its a core feature for any templating system.

    Create forum topic from comment

  6. Sounds good, but what does this mean in real life?
    What are possible use cases for this feature?

    Don’t talk to me foo bar stuff. ( I get this part. Pass on data.)
    But I’m afraid that I don’t quite get the meaning yet.

    Create forum topic from comment

    • One simple example I use in my themes is to pass along the sidebar ID. So, let’s say I have a sidebar.php template to handle multiple dynamic sidebars. Instead of creating a template for each of the sidebars, I can pass the sidebar ID to the template so that it outputs the correct sidebar widgets.

      So, when calling my footer sidebar, I can do something like and pass along the sidebar ID:

      <?php get_sidebar( 'footer', [ 'sidebar_id' => 'footer' ] ) ?>

      That will look for a sidebar-footer.php and fall back to sidebar.php. Let’s assume I don’t create a sidebar-footer.php. My main sidebar.php template could handle this footer sidebar (or any other) like so:

      <!-- open html -->

<?php dynamic_sidebar( $args['sidebar_id'] ) ?>

<!-- close html -->

      If all the sidebars have the same markup, there’s no need for individual templates. I can just pass the ID that I need.

      This is an overly simple example, but I hope it illustrates how this feature can be used. As you get into more complex setups, you’ll find that you could use this in more and more ways.

      Most templating systems for other PHP frameworks start with the notion that you’re passing data into templates. WordPress generally works based on a set of global variables and “template functions” (i.e., the_title(), the_content(), etc.). Other templating systems would usually pass that data along via a variable instead. Often, the idea is to separate the logic code from the template code. But, I’m starting to venture into a much larger discussion.

      Create forum topic from comment

      • Thank you, Justin!

        Let’s see if I got it now.

        The old way I had to build a template for every sidebar (sidebar-footer.php, sidebar-blog.php and so on). Which was indeed somewhat strange.
        Now, in the new era, I will build only one sidebar.php template where I call the IDs directly from the functions.php. I can call this sidebar (with ID) from every template/template-part.

        So the point is I can define something in functions.php and access this from inside any template part, right?

        I wonder if this new way of accessing data will have any impact on the theme colors conundrum. With that I mean that Gutenberg colors are defined inside functions.php but I cant’t really do something with these colors. They just sit there.
        I can output some inline CSS but that’s about it.

        I am constantly looking for a connection of my theme design system (build on SASS) and the Gutenberg color palette. There are workarounds with custom properties, but I haven’t found one yet that works for me.

        Create forum topic from comment

  8. About passing variables to sub-template.

    Believe or not, I able to do the same thing long time ago. This movement is too slow.

    https://github.com/barrel/barrel-wordpress/blob/master/wp-content/themes/barrel-base/lib/helpers/modules.php#L21

    Shopify now moves to “render” which brings variables inside, but limited it there and don’t need to reset variables back.

    https://shopify.dev/changelog/deprecating-the-include-liquid-tag-and-introducing-the-render-tag

    Create forum topic from comment

    • The downside of that is you lose the ability for child themes to override the template and cannot use any of the hooks associated with it. It also wouldn’t be allowed in the WordPress theme directory.

      You could include locate_template() to allow child theme overrides and pass theme review guidelines. You’d still lose the hooks associated with get_template_part() in that case.

      Create forum topic from comment

  11. I skipped using get_template_part() function many times as we can’t pass the variable to that template part file, Finally it is possible with WordPress 5.5.

    But when we use the “passing variable” feature in our theme, it won’t work in the earlier versions of WordPress. So the minimum requirement to run our theme is WordPress 5.5.

    Create forum topic from comment

You may also like

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.