WordPress.org
Get WordPress

Make WordPress Core

Changeset 48370


Ignore:
Timestamp:
07/07/2020 11:00:21 AM (4 years ago)
Author:
SergeyBiryukov
Message:

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

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.

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/general-template.php

    r48311 r48370  
    1818 * @since 1.5.0
    1919 * @since 5.5.0 A return value was added.
     20 * @since 5.5.0 The `$args` parameter was added.
    2021 *
    2122 * @param string $name The name of the specialised header.
     23 * @param array  $args Optional. Additional arguments passed to the header template.
     24 *                     Default empty array.
    2225 * @return void|false Void on success, false if the template does not exist.
    2326 */
    24 function get_header( $name = null ) {
     27function get_header( $name = null, $args = array() ) {
    2528    /**
    2629     * Fires before the header template file is loaded.
    2730     *
    2831     * @since 2.1.0
    29      * @since 2.8.0 $name parameter added.
    30      *
    31      * @param string|null $name Name of the specific header file to use. null for the default header.
    32      */
    33     do_action( 'get_header', $name );
     32     * @since 2.8.0 The `$name` parameter was added.
     33     * @since 5.5.0 The `$args` parameter was added.
     34     *
     35     * @param string|null $name Name of the specific header file to use. Null for the default header.
     36     * @param array       $args Additional arguments passed to the header template.
     37     */
     38    do_action( 'get_header', $name, $args );
    3439
    3540    $templates = array();
    … …  
    4146    $templates[] = 'header.php';
    4247
    43     if ( ! locate_template( $templates, true ) ) {
     48    if ( ! locate_template( $templates, true, true, $args ) ) {
    4449        return false;
    4550    }
    … …  
    5762 * @since 1.5.0
    5863 * @since 5.5.0 A return value was added.
     64 * @since 5.5.0 The `$args` parameter was added.
    5965 *
    6066 * @param string $name The name of the specialised footer.
     67 * @param array  $args Optional. Additional arguments passed to the footer template.
     68 *                     Default empty array.
    6169 * @return void|false Void on success, false if the template does not exist.
    6270 */
    63 function get_footer( $name = null ) {
     71function get_footer( $name = null, $args = array() ) {
    6472    /**
    6573     * Fires before the footer template file is loaded.
    6674     *
    6775     * @since 2.1.0
    68      * @since 2.8.0 $name parameter added.
    69      *
    70      * @param string|null $name Name of the specific footer file to use. null for the default footer.
    71      */
    72     do_action( 'get_footer', $name );
     76     * @since 2.8.0 The `$name` parameter was added.
     77     * @since 5.5.0 The `$args` parameter was added.
     78     *
     79     * @param string|null $name Name of the specific footer file to use. Null for the default footer.
     80     * @param array       $args Additional arguments passed to the footer template.
     81     */
     82    do_action( 'get_footer', $name, $args );
    7383
    7484    $templates = array();
    … …  
    8090    $templates[] = 'footer.php';
    8191
    82     if ( ! locate_template( $templates, true ) ) {
     92    if ( ! locate_template( $templates, true, true, $args ) ) {
    8393        return false;
    8494    }
    … …  
    96106 * @since 1.5.0
    97107 * @since 5.5.0 A return value was added.
     108 * @since 5.5.0 The `$args` parameter was added.
    98109 *
    99110 * @param string $name The name of the specialised sidebar.
     111 * @param array  $args Optional. Additional arguments passed to the sidebar template.
     112 *                     Default empty array.
    100113 * @return void|false Void on success, false if the template does not exist.
    101114 */
    102 function get_sidebar( $name = null ) {
     115function get_sidebar( $name = null, $args = array() ) {
    103116    /**
    104117     * Fires before the sidebar template file is loaded.
    105118     *
    106119     * @since 2.2.0
    107      * @since 2.8.0 $name parameter added.
    108      *
    109      * @param string|null $name Name of the specific sidebar file to use. null for the default sidebar.
    110      */
    111     do_action( 'get_sidebar', $name );
     120     * @since 2.8.0 The `$name` parameter was added.
     121     * @since 5.5.0 The `$args` parameter was added.
     122     *
     123     * @param string|null $name Name of the specific sidebar file to use. Null for the default sidebar.
     124     * @param array       $args Additional arguments passed to the sidebar template.
     125     */
     126    do_action( 'get_sidebar', $name, $args );
    112127
    113128    $templates = array();
    … …  
    119134    $templates[] = 'sidebar.php';
    120135
    121     if ( ! locate_template( $templates, true ) ) {
     136    if ( ! locate_template( $templates, true, true, $args ) ) {
    122137        return false;
    123138    }
    … …  
    142157 * @since 3.0.0
    143158 * @since 5.5.0 A return value was added.
     159 * @since 5.5.0 The `$args` parameter was added.
    144160 *
    145161 * @param string $slug The slug name for the generic template.
    146162 * @param string $name The name of the specialised template.
     163 * @param array  $args Optional. Additional arguments passed to the template.
     164 *                     Default empty array.
    147165 * @return void|false Void on success, false if the template does not exist.
    148166 */
    149 function get_template_part( $slug, $name = null ) {
     167function get_template_part( $slug, $name = null, $args = array() ) {
    150168    /**
    151169     * Fires before the specified template part file is loaded.
    … …  
    155173     *
    156174     * @since 3.0.0
     175     * @since 5.5.0 The `$args` parameter was added.
    157176     *
    158177     * @param string      $slug The slug name for the generic template.
    159178     * @param string|null $name The name of the specialized template.
    160      */
    161     do_action( "get_template_part_{$slug}", $slug, $name );
     179     * @param array       $args Additional arguments passed to the template.
     180     */
     181    do_action( "get_template_part_{$slug}", $slug, $name, $args );
    162182
    163183    $templates = array();
    … …  
    173193     *
    174194     * @since 5.2.0
     195     * @since 5.5.0 The `$args` parameter was added.
    175196     *
    176197     * @param string   $slug      The slug name for the generic template.
    177198     * @param string   $name      The name of the specialized template.
    178199     * @param string[] $templates Array of template files to search for, in order.
    179      */
    180     do_action( 'get_template_part', $slug, $name, $templates );
    181 
    182     if ( ! locate_template( $templates, true, false ) ) {
     200     * @param array    $args      Additional arguments passed to the template.
     201     */
     202    do_action( 'get_template_part', $slug, $name, $templates, $args );
     203
     204    if ( ! locate_template( $templates, true, false, $args ) ) {
    183205        return false;
    184206    }
    … …  
    203225 *
    204226 * @since 2.7.0
    205  * @since 5.2.0 The $args array parameter was added in place of an $echo boolean flag.
     227 * @since 5.2.0 The `$args` array parameter was added in place of an `$echo` boolean flag.
    206228 *
    207229 * @param array $args {
    … …  
    221243     * @since 2.7.0 as 'get_search_form' action.
    222244     * @since 3.6.0
     245     * @since 5.5.0 The `$args` parameter was added.
    223246     *
    224247     * @link https://core.trac.wordpress.org/ticket/19321
    225      */
    226     do_action( 'pre_get_search_form' );
     248     *
     249     * @param array $args The array of arguments for building the search form.
     250     */
     251    do_action( 'pre_get_search_form', $args );
    227252
    228253    $echo = true;
    … …  
    263288     *
    264289     * @since 3.6.0
     290     * @since 5.5.0 The `$args` parameter was added.
    265291     *
    266292     * @param string $format The type of markup to use in the search form.
    267293     *                       Accepts 'html5', 'xhtml'.
    268      */
    269     $format = apply_filters( 'search_form_format', $format );
     294     * @param array  $args   The array of arguments for building the search form.
     295     */
     296    $format = apply_filters( 'search_form_format', $format, $args );
    270297
    271298    $search_form_template = locate_template( 'searchform.php' );
    … …  
    309336     *
    310337     * @since 2.7.0
     338     * @since 5.5.0 The `$args` parameter was added.
    311339     *
    312340     * @param string $form The search form HTML output.
    313      */
    314     $result = apply_filters( 'get_search_form', $form );
     341     * @param array  $args The array of arguments for building the search form.
     342     */
     343    $result = apply_filters( 'get_search_form', $form, $args );
    315344
    316345    if ( null === $result ) {

  • trunk/src/wp-includes/template.php

    r47808 r48370  
    645645 *
    646646 * @since 2.7.0
     647 * @since 5.5.0 The `$args` parameter was added.
    647648 *
    648649 * @param string|array $template_names Template file(s) to search for, in order.
    649650 * @param bool         $load           If true the template file will be loaded if it is found.
    650  * @param bool         $require_once   Whether to require_once or require. Default true. Has no effect if $load is false.
     651 * @param bool         $require_once   Whether to require_once or require. Has no effect if `$load` is false.
     652 *                                     Default true.
     653 * @param array        $args           Optional. Additional arguments passed to the template.
     654 *                                     Default empty array.
    651655 * @return string The template filename if one is located.
    652656 */
    653 function locate_template( $template_names, $load = false, $require_once = true ) {
     657function locate_template( $template_names, $load = false, $require_once = true, $args = array() ) {
    654658    $located = '';
    655659    foreach ( (array) $template_names as $template_name ) {
    … …  
    670674
    671675    if ( $load && '' !== $located ) {
    672         load_template( $located, $require_once );
     676        load_template( $located, $require_once, $args );
    673677    }
    674678
    … …  
    684688 *
    685689 * @since 1.5.0
     690 * @since 5.5.0 The `$args` parameter was added.
    686691 *
    687692 * @global array      $posts
    … …  
    699704 * @param string $_template_file Path to template file.
    700705 * @param bool   $require_once   Whether to require_once or require. Default true.
    701  */
    702 function load_template( $_template_file, $require_once = true ) {
     706 * @param array  $args           Optional. Additional arguments passed to the template.
     707 *                               Default empty array.
     708 */
     709function load_template( $_template_file, $require_once = true, $args = array() ) {
    703710    global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
    704711

  • trunk/tests/phpunit/data/themedir1/default/template-part.php

    r46586 r48370  
    11Template Part
     2
     3<?php echo json_encode( $args ); ?>

  • trunk/tests/phpunit/tests/general/template.php

    r48209 r48370  
    679679        $this->assertFalse( get_template_part( 'non-existing-template' ) );
    680680    }
     681
     682    /**
     683     * @ticket 21676
     684     */
     685    function test_get_template_part_passes_arguments_to_template() {
     686        $this->expectOutputRegex( '/{"foo":"baz"}/' );
     687
     688        get_template_part( 'template', 'part', array( 'foo' => 'baz' ) );
     689    }
    681690}
Note: See TracChangeset for help on using the changeset viewer.