theme_templates │ хук-фільтр │ WP 4.9.6

Дозволяє додати/видалити файли-шаблони сторінок (постів), які використовуються в селекті вибору шаблону запису під час редагування запису.

Цей фільтр є загальним всім типів постів. Щоб не робити в коді перевірку на тип запису, можна скористатися схожим фільтром theme_(post_type)_templates .

Використання

add_filter( 'theme_templates', 'wp_kama_theme_templates_filter', 10, 4);

/**
 * Function for `theme_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 Це повідомлення, яке було виконано, передбачено для контексту, або null.
 * @param string $post_type Post type to get the templates for.
 *
 * @return string[]
 */
function wp_kama_theme_templates_filter( $post_templates, $theme, $post, $post_type ){

	// Filter...
	return $post_templates;
}

$post_templates (масив)

Масив файлів-шаблонів для постів. Ключ масиву – це шлях до файлу щодо папки теми, значення – це ім’я файлу-шаблону.

Array(
	[page-my-tpl.php] => Мій супер шаблон у корені теми
	[template/page-default.php] => Мій дефолтний шаблон у папці template
	[template/portfolio/page-full.php] => Шаблон портфоліо на всю ширину в папці template -> portfolio
	[template/portfolio/page-mini.php] => Шаблон портфоліо мінімальний у папці template -> portfolio
)

$this (WP_Theme)

Примірник класу
WP_Theme .

$post (WP_Post/null)

Об’єкт запису (під час редагування) або null.

$post_type (рядок)

Тип запису, для якого запитується список шаблонів.

Приклади

#1 Додамо свій шаблон до списку всіх типів записів

WordPress за замовчуванням шукає шаблони в корені теми та в папках 1 рівня. Додамо свій шаблон у глибшій папці.

Ми додаємо шаблон без перевірки на тип запису, а значить, він буде доступний для всіх типів постів.

add_filter( 'theme_templates', 'add_my_template_to_list', 10, 4);

function add_my_template_to_list( $templates, $wp_theme, $post, $post_type ) {
	$templates['template/defaults/page.php'] = 'Мій дефолтний шаблон';

	return $templates;
}

#2 Додамо свій шаблон до списку сторінок

Додамо до масиву з шаблонами свій шаблон, тільки якщо він запитується для сторінок: post_type=page .

add_filter( 'theme_templates', 'add_my_template_to_list', 10, 4);

function add_my_template_to_list( $templates, $wp_theme, $post, $post_type ) {
	if ( 'page' === $post_type ) {
		$templates['template/defaults/page.php'] = 'Мій дефолтний шаблон сторінки';
	}

	return $templates;
}

Якщо у вас інший тип запису, то page замініть потрібний тип або, щоб не робити перевірку в коді, можна використовувати схожий хук theme_(post_type)_templates .

#3 Додамо свій шаблон із плагіна

Нехай нам потрібна сторінка зі своїм індивідуальним шаблоном, який потрібно додати за допомогою плагіна. Створимо плагін з наступною структурою:

plugin-my-tpl (папка плагіна)
├── plugin-my-tpl.php (основний файл плагіна)
└── templates (папка із шаблонами)
		├── page-tpl-1.php (шаблон №1)
		└── page-tpl-2.php (шаблон №2)

Файл`plugin-my-tpl.php`

/**
 * Plugin Name: plugin-my-tpl
 */

add_filter( 'theme_templates', 'add_my_template_to_list', 10, 4);
add_filter( 'template_include', 'my_plugin_template_include');

// Додаємо до списку свої шаблони для сторінок
function add_my_template_to_list( $templates, $wp_theme, $post, $post_type ) {
	if ( 'page' === $post_type ) {
		// Доповнюємо масив шаблонів своїми власними
		$templates += my_plugin_templates();
	}

	return $templates;
}

// Формуємо масив із шаблонами
function my_plugin_templates() {
	$ base_path = basename( __DIR__ );

	return [
		$ base_path . '/templates/page-tpl-1.php' => 'Шаблон із плагіна №1',
		$ base_path . '/templates/page-tpl-2.php' => 'Шаблон із плагіна №2',
	];
}

// Підключає шаблон сторінки з плагіна
function my_plugin_template_include( $template ) {
	// Якщо це не сторінка - повертаємо що є
	if ( ! is_page() ) {
		return $template;
	}

	// Отримуємо збережений шаблон
	$path_slug = get_post_meta( get_the_ID(), '_wp_page_template', true );

	// Якщо шаблон не плагіна - повертаємо що є
	if ( ! in_array( $path_slug, array_keys( my_plugin_templates() ) ) ) {
		return $template;
	}

	// Створюємо повний шлях до файлу
	$path_file = wp_normalize_path( WP_PLUGIN_DIR . '/' . $path_slug );

	// Перевіряємо, чи є фізично файл шаблону і, якщо так - віддаємо движку
	if ( file_exists ( $ path_file ) ) {
		return $ path_file;
	}

	return $template;
}

Рішення в стилі ООП можна переглянути у статті Add Page Templates to WordPress with a Plugin .