locate_template( string|array $template_names, bool $load = false, bool $load_once = true, array $args = array() ): string
- Since
- 2.7.0, 5.5.0
- Source
wp-includes/template.php:722
Retrieves the name of the highest priority template file that exists.
Description
Searches in the stylesheet directory before the template directory and wp-includes/theme-compat so that themes which inherit from a parent theme can just overload one file.
Parameters
$template_namesstring|array- Template file(s) to search for, in order.
$loadbooloptional- If true the template file will be loaded if it is found.Default:
false $load_oncebooloptional- Whether to require_once or require. Has no effect if
$loadis false. Default true.Default:true $argsarrayoptional- Additional arguments passed to the template. Default empty array.Default:
array()
Return
string- The template filename if one is located.
Uses · 3
- wp_set_template_globals()Set up the globals used for template loading.
- is_child_theme()Whether a child theme is in use.
- load_template()Requires the template file with WordPress environment.
Used by · 8
- get_footer()Loads footer template.
- get_header()Loads header template.
- get_query_template()Retrieves path to a template.
- get_search_form()Displays search form.
- get_sidebar()Loads sidebar template.
- get_template_part()Loads a template part into a template.
- twentyfifteen_author_bio_template()Prevents `author-bio.php` partial template from interfering with rendering an author archive of a user with the `bio` username.
- twentythirteen_author_bio_template()Prevents `author-bio.php` partial template from interfering with rendering an author archive of a user with the `bio` username.
Source
function locate_template( $template_names, $load = false, $load_once = true, $args = array() ) { global $wp_stylesheet_path, $wp_template_path; if ( ! isset( $wp_stylesheet_path ) || ! isset( $wp_template_path ) ) { wp_set_template_globals(); } $is_child_theme = is_child_theme(); $located = ''; foreach ( (array) $template_names as $template_name ) { if ( ! $template_name ) { continue; } if ( file_exists( $wp_stylesheet_path . '/' . $template_name ) ) { $located = $wp_stylesheet_path . '/' . $template_name; break; } elseif ( $is_child_theme && file_exists( $wp_template_path . '/' . $template_name ) ) { $located = $wp_template_path . '/' . $template_name; break; } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) { $located = ABSPATH . WPINC . '/theme-compat/' . $template_name; break; } } if ( $load && '' !== $located ) { load_template( $located, $load_once, $args ); } return $located;}History
Introduced in 2.7.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
5.5.0
The
$args parameter was added.from the docblock2.7.0
Introduced.from the docblock
About this page
- Parsed data
- Generated from the wordpress-develop 7.0.4 tag, from
src/wp-includes/template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.