Passing arguments to template files in WordPress 5.5

For years, theme developers wishing to pass data to template files have had to use less than ideal workarounds. This included the use of global variables, set_query_var(), the include( locate_template() ) pattern, or own version of get_template_part(), and so on.

Starting in WordPress 5.5, the template loading functions will now allow additional arguments to be passed through to the matched template file using a new $args parameter.

Affected functions

1. get_header()
2. get_footer()
3. get_sidebar()
4. get_template_part()
5. locate_template()
6. load_template()

To provide proper context, the related action hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. have also been updated to pass this new $args parameter.

• get_header
• get_footer
• get_sidebar
• get_template_part_{$slug}
• get_template_part

Note: get_search_form() already accepts and passes additional arguments to search form templates as of [44956]. However, the $args parameter was added to the related hooks at the same time as the ones above. These are:

• pre_get_search_form (action)
• search_form_format (filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output.)
• get_search_form (filter)

Example

<?php
get_template_part( 
    'foo', 
    null, 
    array( 
        'class'          => 'user',
        'arbitrary_data' => array(
            'foo' => 'baz',
            'bar' => true,
        ),
        ...
    )
);

In the above example, the additional data passed to get_template_part() through the $args variable can be accessed within the foo.php template through the locally scoped $args variable.

<?php
// Example foo.php template.

// Set defaults.
$args = wp_parse_args(
    $args,
    array(
        'class'          => '',
        'arbitrary_data' => array(
            'foo' => 'fooval',
            'bar' => false,
        ),
        ...
    )
);
?>

<div class="widget <?php echo esc_html_class( $args['class'] ); ?>">
    <?php echo esc_html( $args['arbitrary_data']['foo'] ); ?>
</div>

Note: Any template file that currently contains an $args variable should take care when utilizing this new feature. Any modifications to $args in the loaded template files will override any values passed through using the above functions.

This enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. ticketticket Created for both bug reports and feature development on the bug tracker. was created 8 years ago, and is a long awaited addition. Thank you to all that helped discuss and refine this change.

For reference, see the related TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket: #21676.

Props @audrasjb and @desrosj for technical review and proofreading.

#5-5, #dev-notes