sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Themes: Allow template loading functions to pass additional arguments to the template via the $args parameter.

Browse Source 
This affects:
* `get_header()`
* `get_footer()`
* `get_sidebar()`
* `get_template_part()`
* `locate_template()`
* `load_template()`

Note: `get_search_form()` already passes additional arguments to the template as of [44956].

Props enrico.sorcinelli, sc0ttkclark, scribu, nacin, wonderboymusic, GeertDD, beatpanda, amaschas, mintindeed, ysalame, caiocrcosta, bigdawggi, julianm, eddiemoya, shawnz, sayedwp, shamai, mboynes, mihai2u, guidobras, Mte90, apedog, stuffradio, overclokk, johnbillion, joyously, afercia, audrasjb, justlevine, SergeyBiryukov.
See #21676.

git-svn-id: https://develop.svn.wordpress.org/trunk@48370 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Sergey Biryukov 2020-07-07 11:00:21 +00:00
parent 3eb2bd9f5b
commit 4e78b0acd9
4 changed files with 74 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
src/wp-includes/general-template.php
View File

@ -17,20 +17,25 @@
* *
* @since 1.5.0 * @since 1.5.0
* @since 5.5.0 A return value was added. * @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $name The name of the specialised header. * @param string $name The name of the specialised header.
* @param array $args Optional. Additional arguments passed to the header template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist. * @return void|false Void on success, false if the template does not exist.
*/ */
function get_header( $name = null ) { function get_header( $name = null, $args = array() ) {
/** /**
* Fires before the header template file is loaded. * Fires before the header template file is loaded.
* *
* @since 2.1.0 * @since 2.1.0
* @since 2.8.0 $name parameter added. * @since 2.8.0 The `$name` parameter was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string|null $name Name of the specific header file to use. null for the default header. * @param string|null $name Name of the specific header file to use. Null for the default header.
* @param array $args Additional arguments passed to the header template.
*/ */
do_action( 'get_header', $name ); do_action( 'get_header', $name, $args );
$templates = array(); $templates = array();
$name = (string) $name; $name = (string) $name;
@ -40,7 +45,7 @@ function get_header( $name = null ) {
$templates[] = 'header.php'; $templates[] = 'header.php';
if ( ! locate_template( $templates, true ) ) { if ( ! locate_template( $templates, true, true, $args ) ) {
return false; return false;
} }
} }
@ -56,20 +61,25 @@ function get_header( $name = null ) {
* *
* @since 1.5.0 * @since 1.5.0
* @since 5.5.0 A return value was added. * @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $name The name of the specialised footer. * @param string $name The name of the specialised footer.
* @param array $args Optional. Additional arguments passed to the footer template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist. * @return void|false Void on success, false if the template does not exist.
*/ */
function get_footer( $name = null ) { function get_footer( $name = null, $args = array() ) {
/** /**
* Fires before the footer template file is loaded. * Fires before the footer template file is loaded.
* *
* @since 2.1.0 * @since 2.1.0
* @since 2.8.0 $name parameter added. * @since 2.8.0 The `$name` parameter was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string|null $name Name of the specific footer file to use. null for the default footer. * @param string|null $name Name of the specific footer file to use. Null for the default footer.
* @param array $args Additional arguments passed to the footer template.
*/ */
do_action( 'get_footer', $name ); do_action( 'get_footer', $name, $args );
$templates = array(); $templates = array();
$name = (string) $name; $name = (string) $name;
@ -79,7 +89,7 @@ function get_footer( $name = null ) {
$templates[] = 'footer.php'; $templates[] = 'footer.php';
if ( ! locate_template( $templates, true ) ) { if ( ! locate_template( $templates, true, true, $args ) ) {
return false; return false;
} }
} }
@ -95,20 +105,25 @@ function get_footer( $name = null ) {
* *
* @since 1.5.0 * @since 1.5.0
* @since 5.5.0 A return value was added. * @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $name The name of the specialised sidebar. * @param string $name The name of the specialised sidebar.
* @param array $args Optional. Additional arguments passed to the sidebar template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist. * @return void|false Void on success, false if the template does not exist.
*/ */
function get_sidebar( $name = null ) { function get_sidebar( $name = null, $args = array() ) {
/** /**
* Fires before the sidebar template file is loaded. * Fires before the sidebar template file is loaded.
* *
* @since 2.2.0 * @since 2.2.0
* @since 2.8.0 $name parameter added. * @since 2.8.0 The `$name` parameter was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string|null $name Name of the specific sidebar file to use. null for the default sidebar. * @param string|null $name Name of the specific sidebar file to use. Null for the default sidebar.
* @param array $args Additional arguments passed to the sidebar template.
*/ */
do_action( 'get_sidebar', $name ); do_action( 'get_sidebar', $name, $args );
$templates = array(); $templates = array();
$name = (string) $name; $name = (string) $name;
@ -118,7 +133,7 @@ function get_sidebar( $name = null ) {
$templates[] = 'sidebar.php'; $templates[] = 'sidebar.php';
if ( ! locate_template( $templates, true ) ) { if ( ! locate_template( $templates, true, true, $args ) ) {
return false; return false;
} }
} }
@ -141,12 +156,15 @@ function get_sidebar( $name = null ) {
* *
* @since 3.0.0 * @since 3.0.0
* @since 5.5.0 A return value was added. * @since 5.5.0 A return value was added.
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $slug The slug name for the generic template. * @param string $slug The slug name for the generic template.
* @param string $name The name of the specialised template. * @param string $name The name of the specialised template.
* @param array $args Optional. Additional arguments passed to the template.
* Default empty array.
* @return void|false Void on success, false if the template does not exist. * @return void|false Void on success, false if the template does not exist.
*/ */
function get_template_part( $slug, $name = null ) { function get_template_part( $slug, $name = null, $args = array() ) {
/** /**
* Fires before the specified template part file is loaded. * Fires before the specified template part file is loaded.
* *
@ -154,11 +172,13 @@ function get_template_part( $slug, $name = null ) {
* for the generic template part. * for the generic template part.
* *
* @since 3.0.0 * @since 3.0.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $slug The slug name for the generic template. * @param string $slug The slug name for the generic template.
* @param string|null $name The name of the specialized template. * @param string|null $name The name of the specialized template.
* @param array $args Additional arguments passed to the template.
*/ */
do_action( "get_template_part_{$slug}", $slug, $name ); do_action( "get_template_part_{$slug}", $slug, $name, $args );
$templates = array(); $templates = array();
$name = (string) $name; $name = (string) $name;
@ -172,14 +192,16 @@ function get_template_part( $slug, $name = null ) {
* Fires before a template part is loaded. * Fires before a template part is loaded.
* *
* @since 5.2.0 * @since 5.2.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $slug The slug name for the generic template. * @param string $slug The slug name for the generic template.
* @param string $name The name of the specialized template. * @param string $name The name of the specialized template.
* @param string[] $templates Array of template files to search for, in order. * @param string[] $templates Array of template files to search for, in order.
* @param array $args Additional arguments passed to the template.
*/ */
do_action( 'get_template_part', $slug, $name, $templates ); do_action( 'get_template_part', $slug, $name, $templates, $args );
if ( ! locate_template( $templates, true, false ) ) { if ( ! locate_template( $templates, true, false, $args ) ) {
return false; return false;
} }
} }
@ -202,7 +224,7 @@ function get_template_part( $slug, $name = null ) {
* search. To give a few examples of what it can be used for. * search. To give a few examples of what it can be used for.
* *
* @since 2.7.0 * @since 2.7.0
* @since 5.2.0 The $args array parameter was added in place of an $echo boolean flag. * @since 5.2.0 The `$args` array parameter was added in place of an `$echo` boolean flag.
* *
* @param array $args { * @param array $args {
* Optional. Array of display arguments. * Optional. Array of display arguments.
@ -220,10 +242,13 @@ function get_search_form( $args = array() ) {
* *
* @since 2.7.0 as 'get_search_form' action. * @since 2.7.0 as 'get_search_form' action.
* @since 3.6.0 * @since 3.6.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @link https://core.trac.wordpress.org/ticket/19321 * @link https://core.trac.wordpress.org/ticket/19321
*
* @param array $args The array of arguments for building the search form.
*/ */
do_action( 'pre_get_search_form' ); do_action( 'pre_get_search_form', $args );
$echo = true; $echo = true;
@ -262,11 +287,13 @@ function get_search_form( $args = array() ) {
* Filters the HTML format of the search form. * Filters the HTML format of the search form.
* *
* @since 3.6.0 * @since 3.6.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $format The type of markup to use in the search form. * @param string $format The type of markup to use in the search form.
* Accepts 'html5', 'xhtml'. * Accepts 'html5', 'xhtml'.
* @param array $args The array of arguments for building the search form.
*/ */
$format = apply_filters( 'search_form_format', $format ); $format = apply_filters( 'search_form_format', $format, $args );
$search_form_template = locate_template( 'searchform.php' ); $search_form_template = locate_template( 'searchform.php' );
@ -308,10 +335,12 @@ function get_search_form( $args = array() ) {
* Filters the HTML output of the search form. * Filters the HTML output of the search form.
* *
* @since 2.7.0 * @since 2.7.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string $form The search form HTML output. * @param string $form The search form HTML output.
* @param array $args The array of arguments for building the search form.
*/ */
$result = apply_filters( 'get_search_form', $form ); $result = apply_filters( 'get_search_form', $form, $args );
if ( null === $result ) { if ( null === $result ) {
$result = $form; $result = $form;

15
src/wp-includes/template.php
View File

@ -644,13 +644,17 @@ function get_attachment_template() {
* so that themes which inherit from a parent theme can just overload one file. * so that themes which inherit from a parent theme can just overload one file.
* *
* @since 2.7.0 * @since 2.7.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @param string|array $template_names Template file(s) to search for, in order. * @param string|array $template_names Template file(s) to search for, in order.
* @param bool $load If true the template file will be loaded if it is found. * @param bool $load If true the template file will be loaded if it is found.
* @param bool $require_once Whether to require_once or require. Default true. Has no effect if $load is false. * @param bool $require_once Whether to require_once or require. Has no effect if `$load` is false.
* Default true.
* @param array $args Optional. Additional arguments passed to the template.
* Default empty array.
* @return string The template filename if one is located. * @return string The template filename if one is located.
*/ */
function locate_template( $template_names, $load = false, $require_once = true ) { function locate_template( $template_names, $load = false, $require_once = true, $args = array() ) {
$located = ''; $located = '';
foreach ( (array) $template_names as $template_name ) { foreach ( (array) $template_names as $template_name ) {
if ( ! $template_name ) { if ( ! $template_name ) {
@ -669,7 +673,7 @@ function locate_template( $template_names, $load = false, $require_once = true )
} }
if ( $load && '' !== $located ) { if ( $load && '' !== $located ) {
load_template( $located, $require_once ); load_template( $located, $require_once, $args );
} }
return $located; return $located;
@ -683,6 +687,7 @@ function locate_template( $template_names, $load = false, $require_once = true )
* also available. * also available.
* *
* @since 1.5.0 * @since 1.5.0
* @since 5.5.0 The `$args` parameter was added.
* *
* @global array $posts * @global array $posts
* @global WP_Post $post Global post object. * @global WP_Post $post Global post object.
@ -698,8 +703,10 @@ function locate_template( $template_names, $load = false, $require_once = true )
* *
* @param string $_template_file Path to template file. * @param string $_template_file Path to template file.
* @param bool $require_once Whether to require_once or require. Default true. * @param bool $require_once Whether to require_once or require. Default true.
* @param array $args Optional. Additional arguments passed to the template.
* Default empty array.
*/ */
function load_template( $_template_file, $require_once = true ) { function load_template( $_template_file, $require_once = true, $args = array() ) {
global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID; global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
if ( is_array( $wp_query->query_vars ) ) { if ( is_array( $wp_query->query_vars ) ) {

2
tests/phpunit/data/themedir1/default/template-part.php
View File

@ -1 +1,3 @@
Template Part Template Part
<?php echo json_encode( $args ); ?>

9
tests/phpunit/tests/general/template.php
View File

@ -678,4 +678,13 @@ class Tests_General_Template extends WP_UnitTestCase {
function test_get_template_part_returns_false_on_failure() { function test_get_template_part_returns_false_on_failure() {
$this->assertFalse( get_template_part( 'non-existing-template' ) ); $this->assertFalse( get_template_part( 'non-existing-template' ) );
} }
/**
* @ticket 21676
*/
function test_get_template_part_passes_arguments_to_template() {
$this->expectOutputRegex( '/{"foo":"baz"}/' );
get_template_part( 'template', 'part', array( 'foo' => 'baz' ) );
}
} }