bbp_locate_template

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

Description

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

Searches in the child theme before parent theme so that themes which inherit from a parent theme can just overload one file. If the template is not found in either of those, it looks in the theme-compat folder last.

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( 'bbp_locate_template' ) ) { 
  2. require_once ABSPATH . PLUGINDIR . 'bbpress/includes/core/template-functions.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. 
  11. // Has no effect if $load is false. 
  12. $require_once = true; 
  13.  
  14. // NOTICE! Understand what this does before running. 
  15. $result = bbp_locate_template($template_names, $load, $require_once); 
  16.  

Defined (1)

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

/includes/core/template-functions.php  
  1. function bbp_locate_template( $template_names, $load = false, $require_once = true ) { 
  2.  
  3. // No file found yet 
  4. $located = false; 
  5. $template_locations = bbp_get_template_stack(); 
  6.  
  7. // Try to find a template file 
  8. foreach ( (array) $template_names as $template_name ) { 
  9.  
  10. // Continue if template is empty 
  11. if ( empty( $template_name ) ) { 
  12. continue; 
  13.  
  14. // Trim off any slashes from the template name 
  15. $template_name = ltrim( $template_name, '/' ); 
  16.  
  17. // Loop through template stack 
  18. foreach ( (array) $template_locations as $template_location ) { 
  19.  
  20. // Continue if $template_location is empty 
  21. if ( empty( $template_location ) ) { 
  22. continue; 
  23.  
  24. // Check child theme first 
  25. if ( file_exists( trailingslashit( $template_location ) . $template_name ) ) { 
  26. $located = trailingslashit( $template_location ) . $template_name; 
  27. break 2; 
  28.  
  29. /** 
  30. * This action exists only to follow the standard bbPress coding convention,  
  31. * and should not be used to short-circuit any part of the template locator. 
  32. * If you want to override a specific template part, please either filter 
  33. * 'bbp_get_template_part' or add a new location to the template stack. 
  34. */ 
  35. do_action( 'bbp_locate_template', $located, $template_name, $template_names, $template_locations, $load, $require_once ); 
  36.  
  37. // Maybe load the template if one was located 
  38. if ( ( true === $load ) && !empty( $located ) ) { 
  39. load_template( $located, $require_once ); 
  40.  
  41. return $located;