locate_template

Retrieve the name of the highest priority template file that exists.

Description

(string) locate_template( (string) $template_names, (constant) $load = false, (bool) $require_once = true ); 

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.

Returns (string)

The template filename if one is located.

Parameters (3)

0. $template_names (string)
Template file(s) to search for, in order.
1. $load — Optional. (constant) => false
If true the template file will be loaded if it is found.
2. $require_once — Optional. (bool) => true
Whether to require_once or require. Default true. Has no effect if $load is false.

Usage

  1. if ( !function_exists( 'locate_template' ) ) { 
  2. require_once ABSPATH . WPINC . '/template.php'; 
  3.  
  4. // Template file(s) to search for, in order. 
  5. $template_names = ''; 
  6.  
  7. // If true the template file will be loaded if it is found. 
  8. $load = false; 
  9.  
  10. // Whether to require_once or require. Default true. Has no effect if $load is false. 
  11. $require_once = true; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = locate_template($template_names, $load, $require_once); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/template.php  
  1. function locate_template($template_names, $load = false, $require_once = true ) { 
  2. $located = ''; 
  3. foreach ( (array) $template_names as $template_name ) { 
  4. if ( !$template_name ) 
  5. continue; 
  6. if ( file_exists(STYLESHEETPATH . '/' . $template_name)) { 
  7. $located = STYLESHEETPATH . '/' . $template_name; 
  8. break; 
  9. } elseif ( file_exists(TEMPLATEPATH . '/' . $template_name) ) { 
  10. $located = TEMPLATEPATH . '/' . $template_name; 
  11. break; 
  12. } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) { 
  13. $located = ABSPATH . WPINC . '/theme-compat/' . $template_name; 
  14. break; 
  15.  
  16. if ( $load && '' != $located ) 
  17. load_template( $located, $require_once ); 
  18.  
  19. return $located;