Функция locate_template() в WordPress с примерами.

Функция locate_template() в WordPress используется для поиска и возврата пути к файлу шаблона. Она обеспечивает удобный способ для тем и плагинов искать и подключать нужные файлы шаблонов, учитывая при этом наличие дочерней темы. Если требуется, файл может быть сразу подключен через PHP.

locate_template( $template_names, $load = false, $require_once = true, $args = array() )

Параметры

• $template_names (array|string): Массив или строка с именами файлов шаблонов для поиска. Файлы должны включать расширение, например, header.php.
• $load (bool): Если true, файл будет подключен с помощью require_once(). По умолчанию false.
• $require_once (bool): Если true, файл будет загружен с помощью require_once(). По умолчанию true.
• $args (array): Дополнительные параметры для подключаемого файла. Используется переменная $args в подключаемом файле. Доступен с версии WordPress 5.5. По умолчанию array().

Возвращаемое значение

• (string): Путь к найденному файлу шаблона или пустая строка, если файл не найден.

Пример использования

Допустим, у вас есть плагин, который должен загружать пользовательский шаблон. Вы можете использовать locate_template() для поиска и загрузки этого шаблона следующим образом:

function genius_plugin_load_template( $template_name ) {
    // Имена файлов шаблонов для поиска
    $templates = array(
        $template_name . '.php',
        'my-plugin/' . $template_name . '.php'
    );

    // Ищем шаблон в текущей или родительской теме
    $located = locate_template( $templates, true, false );

    // Если шаблон не найден, используем шаблон по умолчанию из плагина
    if ( '' === $located ) {
        $located = plugin_dir_path( __FILE__ ) . 'templates/' . $template_name . '.php';
        require $located;
    }
}

// Пример использования функции
add_action( 'template_redirect', function() {
    if ( is_singular( 'custom_post_type' ) ) {
        genius_plugin_load_template( 'single-custom-post-type' );
        exit;
    }
} );

Подробное объяснение

1. Имена файлов шаблонов: Мы создаем массив $templates, содержащий возможные пути к файлам шаблонов.
2. Поиск шаблона: Функция locate_template() ищет файлы в массиве $templates и возвращает путь к найденному файлу.
3. Загрузка шаблона: Если найденный путь не пустой, файл загружается с помощью require. Если путь пустой, загружается шаблон по умолчанию из папки плагина.
4. Использование функции: Функция вызывается в хук template_redirect, который срабатывает перед загрузкой шаблона. Если условие is_singular( 'custom_post_type' ) истинно, загружается шаблон для типа записи custom_post_type.

Дополнительные примеры

Пример 1: Получение пути файла

echo locate_template('header.php');
// Выведет: /home/example.com/public_html/wp-content/themes/your-theme/header.php

Пример 2: Проверка наличия файла перед подключением

Создадим возможность выводить контент страницы особым образом, если файл шаблона существует. Для этого создадим файл content-<SLUG>.php в теме, который будет использоваться вместо функции the_content():

$page_slug = $post->post_name;
$located_template = locate_template("content-$page_slug.php");

if( $located_template ) {
    // Подключаем файл шаблона
    require $located_template;

    // Или так:
    // get_template_part('content', $page_slug);
} else {
    // Файл не найден, загружаем контент стандартно
    the_content();
}

Пример 3: Указание подпапок

Можно указать не только название файла, но и относительный путь от корня темы:

locate_template('inc/filename.php', true);

Этот код подключит файл filename.php, который находится в папке inc в каталоге дочерней темы или основной темы, если дочерняя тема отсутствует.

Пример 4: Поиск и подключение файла шаблона

Рассмотрим пример, где мы ищем файл шаблона и подключаем его:

$files = array(
    'foo.php', // не существует
    'header.php', // существует, будет возвращен
    'bar.php', // проверяться не будет
);

$file_path = locate_template( $files );

echo $file_path;
// выведет: /home/example.com/wp-content/themes/theme_name/header.php

В данном коде функция locate_template() будет искать файлы в следующем порядке. При первом обнаружении файла поиск прекращается:

1. foo.php в дочерней теме
2. foo.php в родительской теме
3. header.php в дочерней теме
4. header.php в родительской теме
5. bar.php в дочерней теме
6. bar.php в родительской теме

Если в параметре $load указать true, файл будет подключен через require_once().

Используемые функции и константы

• load_template(): Используется для загрузки шаблонов, когда второй параметр равен true.
• Константы STYLESHEETPATH и TEMPLATEPATH: Дочерняя тема имеет приоритет над родительской и может переписывать её файлы.

Заключение

Функция locate_template() возвращает строку с путем до найденного файла или пустую строку, если файл не найден. Она является основой для таких функций, как get_query_template(), get_template_part(), get_sidebar(), get_header(), get_footer(), что делает её важной частью системы шаблонов WordPress.