bp_locate_template( string|array $template_names, bool $load = false, bool $require_once = true, array $args = array() )

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


Description Description

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.


Parameters Parameters

$template_names

(Required) Template file(s) to search for, in order.

$load

(Optional) If true, the template file will be loaded when found. If false, the path will be returned. Default: false.

Default value: false

$require_once

(Optional) Whether to require_once or require. Has no effect if $load is false. Default: true.

Default value: true

$args

(Optional) Extra args to pass to locate_template().

Default value: array()


Top ↑

Return Return

(string) The template filename if one is located.


Top ↑

Source Source

File: bp-core/bp-core-template-loader.php

function bp_locate_template( $template_names, $load = false, $require_once = true ) {

	// Bail when there are no templates to locate
	if ( empty( $template_names ) ) {
		return false;
	}

	// No file found yet.
	$located            = false;
	$template_locations = bp_get_template_stack();

	// Try to find a template file.
	foreach ( (array) $template_names as $template_name ) {

		// Continue if template is empty.
		if ( empty( $template_name ) ) {
			continue;
		}

		// Trim off any slashes from the template name.
		$template_name  = ltrim( $template_name, '/' );

		// Loop through template stack.
		foreach ( (array) $template_locations as $template_location ) {

			// Continue if $template_location is empty.
			if ( empty( $template_location ) ) {
				continue;
			}

			// Check child theme first.
			if ( file_exists( trailingslashit( $template_location ) . $template_name ) ) {
				$located = trailingslashit( $template_location ) . $template_name;
				break 2;
			}
		}
	}

	/**
	 * This action exists only to follow the standard BuddyPress coding convention,
	 * and should not be used to short-circuit any part of the template locator.
	 *
	 * If you want to override a specific template part, please either filter
	 * 'bp_get_template_part' or add a new location to the template stack.
	 */
	do_action( 'bp_locate_template', $located, $template_name, $template_names, $template_locations, $load, $require_once );

	/**
	 * Filter here to allow/disallow template loading.
	 *
	 * @since 2.5.0
	 *
	 * @param bool $value True to load the template, false otherwise.
	 */
	$load_template = (bool) apply_filters( 'bp_locate_template_and_load', true );

	if ( $load_template && $load && ! empty( $located ) ) {
		load_template( $located, $require_once );
	}

	return $located;
}

Top ↑

Changelog Changelog

Changelog
Version Description
7.0.0 Added $args parameter.
1.7.0 Introduced.

Top ↑

User Contributed Notes User Contributed Notes

You must log in before being able to contribute a note or feedback.