theme_(post_type)_templates │ хук-фильтр │ WP 3.9.0

Позволяет добавить/удалить шаблоны страниц для типов записей. Эти шаблоны выбираются при публикации записи в админ-панели.

Шаблоны страниц создаются с помощью комментариев в файле шаблона:

/*
 * Template Name: Мой шаблон страницы
 * Template Post Type: post, page, product
 */

Этот фильтр позволяет:

указать путь к файлу и имя шаблона, когда ВП не может найти этот файл самостоятельно. Или если файл расположен в плагине.
удалить файл шаблона из списка выбора, когда например шаблон есть в теме, но его нужно отключить.

Динамическая часть имени хука, $post_type, указывает на тип записи. Возможные имена хуков:

Смотрите также:

Использование

add_filter( 'theme_(post_type)_templates', 'wp_kama_theme_post_type_templates_filter', 10, 4 );

/**
 * Function for `theme_(post_type)_templates` filter-hook.
 * 
 * @param string[]     $post_templates Array of template header names keyed by the template file name.
 * @param WP_Theme     $theme          The theme object.
 * @param WP_Post|null $post           The post being edited, provided for context, or null.
 * @param string       $post_type      Post type to get the templates for.
 *
 * @return string[]
 */
function wp_kama_theme_post_type_templates_filter( $post_templates, $theme, $post, $post_type ){

	// filter...
	return $post_templates;
}

$post_templates(string[]): Массив шаблонов в виде ключ => значение. Ключ массива указывает на путь к файлу шаблона относительно папки темы, а в значении указывается Название шаблона, которое будет показано в админ-панели.
$theme(WP_Theme): Объект темы - WP_Theme.
$post(WP_Post|null): Объект записи WP_Post, для которой выводится список шаблонов.
$post_type(строка): Тип записи, для которой выводится список шаблонов.

Примеры

#1 Добавим шаблон страницы

Например, у нас в теме есть файл tpl/page/exchanges.php. Как видно файл шаблона лежит в папке tpl/page/ - в этом случае ВП не опознает этот файл как файл шаблона (потому что ВП ищет файлы шаблонов в корне темы и просматривает один уровень папок), но нам нужно добавить этот файл в список возможных шаблонов при создании/редактировании записи:

// Добавим шаблон страницы
add_filter( 'theme_page_templates', 'add_theme_page_templates' );

function add_theme_page_templates( $templates ){

	$templates['tpl/page/exchanges.php'] = 'Exchange Template Page';

	return $templates;
}

Получим в списке:

#2 Удалим имеющийся шаблон страницы из списка

Допустим тема создает шаблоны, которые мы не будем использовать. Удалим эти шаблоны из списка:

// Удалим имеющийся шаблон страницы из списка
add_filter( 'theme_page_templates', 'remove_theme_page_templates' );
add_filter( 'theme_post_templates', 'remove_theme_page_templates' );

function remove_theme_page_templates( $templates ) {

	unset( $templates['template-full-width-cover.php'] );
	unset( $templates['template-full-width.php'] );

	// файл в подпапке
	unset( $templates['template/only-content.php'] );

	return $templates;
}

#3 Фильтр шаблонов страниц по идентификатору блога

Предположим, у вас есть блог Food с id 2 и шаблон page-food.php, который должен использоваться только для этого блога. Приведенный ниже пример удаляет шаблон страницы из выпадающих списков других блогов:

add_filter( 'theme_page_templates', 'wpdocs_filter_theme_page_templates', 20, 3 );

/**
 * Filter the theme page templates.
 *
 * @param array    $page_templates Page templates.
 * @param WP_Theme $this           WP_Theme instance.
 * @param WP_Post  $post           The post being edited, provided for context, or null.
 * @return array (Maybe) modified page templates array.
 */
function wpdocs_filter_theme_page_templates( $page_templates, $this, $post ) {

	$current_blog_id = get_current_blog_id();
	$food_blog_id    = 2;

	if ( $current_blog_id != $food_blog_id ) {

		unset( $page_templates['page-food.php'] );
	}

	return $page_templates;
}

#4 Как добавить файл шаблона темы из плагина

Смотрите заметку: Как создать шаблон страницы из плагина.

Список изменений

С версии 3.9.0	Введена.
С версии 4.4.0	Converted to allow complete control over the `$page_templates` array.
С версии 4.7.0	Added the `$post_type` parameter.

Где вызывается хук

WP_Theme::get_page_templates()

theme_templates

theme_(post_type)_templates

theme_post_templates

theme_page_templates

theme_attachment_templates

wp-includes/class-wp-theme.php 1434

$post_templates = (array) apply_filters( "theme_{$post_type}_templates", $post_templates, $this, $post, $post_type );

Где используется хук в WordPress

wp-includes/default-filters.php 659

add_filter( 'theme_wp_navigation_templates', '__return_empty_array' );