load_template() – Function | Developer.WordPress.org

Requires the template file with WordPress environment.

Description

The globals are set up for the template file to ensure that the WordPress environment is available from within the function. The query variables are also available.

Parameters

$_template_filestringrequired: Path to template file.
$load_oncebooloptional: Whether to require_once or require.
Default:true
$argsarrayoptional: Additional arguments passed to the template.

Default:array()

More Information

Uses global: (object) $wp_query to extract extract() global variables returned by the query_vars method while protecting the current values in these global variables:

(unknown type) $posts
(unknown type) $post
(boolean) $wp_did_header Returns true if the WordPress header was already loaded. See the /wp-blog-header.php file for details.
(boolean) $wp_did_template_redirect
(object) $wp_rewrite
(object) $wpdb
(string) $wp_version holds the installed WordPress version number.
(string) $wp
(string) $id
(string) $comment
(string) $user_ID

Source

function load_template( $_template_file, $load_once = true, $args = array() ) {
	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 ) ) {
		/*
		 * This use of extract() cannot be removed. There are many possible ways that
		 * templates could depend on variables that it creates existing, and no way to
		 * detect and deprecate it.
		 *
		 * Passing the EXTR_SKIP flag is the safest option, ensuring globals and
		 * function variables cannot be overwritten.
		 */
		// phpcs:ignore WordPress.PHP.DontExtract.extract_extract
		extract( $wp_query->query_vars, EXTR_SKIP );
	}

	if ( isset( $s ) ) {
		$s = esc_attr( $s );
	}

	/**
	 * Fires before a template file is loaded.
	 *
	 * @since 6.1.0
	 *
	 * @param string $_template_file The full path to the template file.
	 * @param bool   $load_once      Whether to require_once or require.
	 * @param array  $args           Additional arguments passed to the template.
	 */
	do_action( 'wp_before_load_template', $_template_file, $load_once, $args );

	if ( $load_once ) {
		require_once $_template_file;
	} else {
		require $_template_file;
	}

	/**
	 * Fires after a template file is loaded.
	 *
	 * @since 6.1.0
	 *
	 * @param string $_template_file The full path to the template file.
	 * @param bool   $load_once      Whether to require_once or require.
	 * @param array  $args           Additional arguments passed to the template.
	 */
	do_action( 'wp_after_load_template', $_template_file, $load_once, $args );
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_after_load_template’, string $_template_file, bool $load_once, array $args ): Fires after a template file is loaded.
do_action( ‘wp_before_load_template’, string $_template_file, bool $load_once, array $args ): Fires before a template file is loaded.

Uses	Description
esc_attr()`wp-includes/formatting.php`	Escaping for HTML attributes.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Used by	Description
do_feed_rdf()`wp-includes/functions.php`	Loads the RDF RSS 0.91 Feed template.
do_feed_rss()`wp-includes/functions.php`	Loads the RSS 1.0 Feed Template.
do_feed_rss2()`wp-includes/functions.php`	Loads either the RSS2 comment feed or the RSS2 posts feed.
do_feed_atom()`wp-includes/functions.php`	Loads either Atom comment feed or Atom posts feed.
locate_template()`wp-includes/template.php`	Retrieves the name of the highest priority template file that exists.

Changelog

Version	Description
5.5.0	The `$args` parameter was added.
1.5.0	Introduced.

User Contributed Notes

Codex 10 years ago

Loading a template in a plugin, but allowing theme and child theme to override template

if ( $overridden_template = locate_template( 'some-template.php' ) ) {
	/*
	 * locate_template() returns path to file.
	 * if either the child theme or the parent theme have overridden the template.
	 */
	load_template( $overridden_template );
} else {
	/*
	 * If neither the child nor parent theme have overridden the template,
	 * we load the template from the 'templates' sub-directory of the directory this file is in.
	 */
	load_template( dirname( __FILE__ ) . '/templates/some-template.php' );
}

Skip to note 5 content

webbuilder03 6 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
Send variable with load_template()

you can send additional variable with load_template() . load_template() extracts all of the WP_Query query variables, into the scope of the loaded template.

use set_query_var() to make your variable available to the template part.
```
$template = locate_template('template.php');

if( $template ){

	set_query_var('my_variable ', 'Hello Template File' );

	load_template( $template );
			
}
```
In template.php file you can access this variable like this
```
    //Output will be "Hello Template File"
	echo $my_variable;
    
```
- Note that in recent WordPress `load_template` has a 3rd parameter for passing arguments to the template.
  
  strarsis 2 years ago
Log in to add feedback
Skip to note 6 content

strarsis 2 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

Note that the arguments set in `$args` are not simply made available as variables of the same name (as the key) in the template. Instead they are available in the `$args` variable in the template.
- I think it would be much better if any supplied arguments would be extracted so you could add hints for the variables in the template e.g.
  
  public function renderShortcode(array $args): string { $result = $this->loadNews(); $template = locate_template('news.php'); if (!$template) { $template = __DIR__ . '/templates/news.php'; } ob_start(); load_template($template, true, [ 'result' => $result, ]); return ob_end_clean(); }
  
  The above will not work since we have the $result in the $args variable. I remove this entry since I do not understand how I can make a line break in the code…
  
  cyclonecode 9 months ago
Log in to add feedback

load_template( string $_template_file, bool $load_once = true, array $args = array() )

In this article