locate_template( string|array $template_names, bool $load = false, bool $require_once = true )
Retrieve the name of the highest priority template file that exists.
Description Description
Searches in the STYLESHEETPATH before TEMPLATEPATH and wp-includes/theme-compat so that themes which inherit from a parent theme can just overload one file.
Parameters Parameters
- $template_names
-
(string|array) (Required) Template file(s) to search for, in order.
- $load
-
(bool) (Optional) If true the template file will be loaded if it is found.
Default value: false
- $require_once
-
(bool) (Optional) Whether to require_once or require. Has no effect if $load is false.
Default value: true
Return Return
(string) The template filename if one is located.
Source Source
File: wp-includes/template.php
function locate_template( $template_names, $load = false, $require_once = true ) { $located = ''; foreach ( (array) $template_names as $template_name ) { if ( ! $template_name ) { continue; } if ( file_exists( STYLESHEETPATH . '/' . $template_name ) ) { $located = STYLESHEETPATH . '/' . $template_name; break; } elseif ( file_exists( TEMPLATEPATH . '/' . $template_name ) ) { $located = TEMPLATEPATH . '/' . $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, $require_once ); } return $located; }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
2.7.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Note that
locate_template()
does not prevent directory traversal attacks, so if you’re passing a user-provided template name to the function, be sure to verify that it’s from one of the three appropriate locations (active theme directory, parent theme directory, or /wp-includes/theme-compat/ directory).Example:
Expand full source codeCollapse full source code
Example
Load a specific template part based on the current pagename.