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
get_header()
get_footer()
get_sidebar()
get_template_part()
locate_template()
load_template()
To provide proper context, the related action hooks 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
(filter 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 enhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. ticket 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 Trac 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