bp_locate_template

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

Description

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

Searches in the STYLESHEETPATH before TEMPLATEPATH 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 when found. If false, the path will be returned. Default: false.
2. $require_once — Optional. (bool) => true
Whether to require_once or require. Has no effect if $load is false. Default: true.

Usage

  1. if ( !function_exists( 'bp_locate_template' ) ) { 
  2. require_once ABSPATH . PLUGINDIR . 'buddypress/bp-core/bp-core-template-loader.php'; 
  3.  
  4. // Template file(s) to search for, in order. 
  5. $template_names = ''; 
  6.  
  7. // Optional. If true, the template file will be loaded when 
  8. // found. If false, the path will be returned. Default: false. 
  9. $load = false; 
  10.  
  11. // Optional. Whether to require_once or require. Has 
  12. // no effect if $load is false. Default: true. 
  13. $require_once = true; 
  14.  
  15. // NOTICE! Understand what this does before running. 
  16. $result = bp_locate_template($template_names, $load, $require_once); 
  17.  

Defined (1)

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

/bp-core/bp-core-template-loader.php  
  1. function bp_locate_template( $template_names, $load = false, $require_once = true ) { 
  2.  
  3. // Bail when there are no templates to locate 
  4. if ( empty( $template_names ) ) { 
  5. return false; 
  6.  
  7. // No file found yet. 
  8. $located = false; 
  9. $template_locations = bp_get_template_stack(); 
  10.  
  11. // Try to find a template file. 
  12. foreach ( (array) $template_names as $template_name ) { 
  13.  
  14. // Continue if template is empty. 
  15. if ( empty( $template_name ) ) { 
  16. continue; 
  17.  
  18. // Trim off any slashes from the template name. 
  19. $template_name = ltrim( $template_name, '/' ); 
  20.  
  21. // Loop through template stack. 
  22. foreach ( (array) $template_locations as $template_location ) { 
  23.  
  24. // Continue if $template_location is empty. 
  25. if ( empty( $template_location ) ) { 
  26. continue; 
  27.  
  28. // Check child theme first. 
  29. if ( file_exists( trailingslashit( $template_location ) . $template_name ) ) { 
  30. $located = trailingslashit( $template_location ) . $template_name; 
  31. break 2; 
  32.  
  33. /** 
  34. * This action exists only to follow the standard BuddyPress coding convention,  
  35. * and should not be used to short-circuit any part of the template locator. 
  36. * If you want to override a specific template part, please either filter 
  37. * 'bp_get_template_part' or add a new location to the template stack. 
  38. */ 
  39. do_action( 'bp_locate_template', $located, $template_name, $template_names, $template_locations, $load, $require_once ); 
  40.  
  41. /** 
  42. * Filter here to allow/disallow template loading. 
  43. * @since 2.5.0 
  44. * @param bool $value True to load the template, false otherwise. 
  45. */ 
  46. $load_template = (bool) apply_filters( 'bp_locate_template_and_load', true ); 
  47.  
  48. if ( $load_template && $load && ! empty( $located ) ) { 
  49. load_template( $located, $require_once ); 
  50.  
  51. return $located;