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.   
  5. // Template file(s) to search for, in order. 
  6. $template_names = ''; 
  7.   
  8. // If true the template file will be loaded if it is found. 
  9. $load = false; 
  10.   
  11. // Whether to require_once or require. Default true. Has no effect if $load is false. 
  12. $require_once = true; 
  13.   
  14. // NOTICE! Understand what this does before running. 
  15. $result = locate_template($template_names, $load, $require_once); 
  16.     

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.     } 
  17.  
  18.     if ( $load && '' != $located ) 
  19.         load_template( $located, $require_once ); 
  20.  
  21.     return $located; 
  22. }