register_block_template() │ WP 6.7.0

Регистрирует блочный шаблон страницы для темы.

Шаблон становится доступен в редакторе сайта и может использоваться в иерархии шаблонов WordPress или выбираться для отдельных записей.

Тема и кастомные изменения могут переопределить его содержимое.

Регистрировать шаблоны рекомендуется на событии init.

Функция регистрирует только полные шаблоны wp_template. Части шаблонов wp_template_part она не поддерживает.

Используйте unregister_block_template(), когда нужно удалить зарегистрированный плагином шаблон.

Работает на основе: WP_Block_Templates_Registry::register()

Хуков нет.

Возвращает

WP_Block_Template|WP_Error.

  • WP_Block_Template — объект зарегистрированного шаблона.
  • WP_Error — если имя имеет неверный формат, содержит заглавные буквы или шаблон с таким именем уже зарегистрирован.

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

register_block_template( $template_name, $args );
$template_name(string) (обязательный)

Имя шаблона в формате слаг-плагина//имя-шаблона.

Обе части могут содержать только строчные латинские буквы, цифры, дефисы и символы подчёркивания: a-z 0-9 _ -.

$args(array)

Настройки шаблона.

  • title(string)
    Название шаблона в редакторе сайта и других элементах интерфейса.
    По умолчанию: значение $template_name

  • description(string)
    Описание шаблона в редакторе сайта.
    По умолчанию: ''

  • content(string)
    Исходное содержимое шаблона в формате разметки блоков. Используется при выводе и редактировании шаблона.
    По умолчанию: ''

  • post_types(string[])
    Список типов записей, для которых шаблон можно выбрать.
    По умолчанию: []

  • plugin(string)
    Слаг плагина, зарегистрировавшего шаблон.
    В текущей реализации значение не используется. Слаг определяется по первой части $template_name.

По умолчанию: []

Примеры

#1 Регистрация шаблона для записей типа book

Шаблон появится среди доступных шаблонов записей типа book.

add_action( 'init', 'my_plugin_register_book_template' );

function my_plugin_register_book_template() {
	register_block_template(
		'my-plugin//book-layout',
		[
			'title'       => __( 'Book layout', 'my-plugin' ),
			'description' => __( 'Template for displaying a book.', 'my-plugin' ),
			'content'     => '
				<!-- wp:template-part {"slug":"header","area":"header"} /-->
				<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
				<main class="wp-block-group">
					<!-- wp:post-title {"level":1} /-->
					<!-- wp:post-featured-image /-->
					<!-- wp:post-content /-->
				</main>
				<!-- /wp:group -->
				<!-- wp:template-part {"slug":"footer","area":"footer"} /-->
			',
			'post_types'  => [ 'book' ],
		]
	);
}

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

С версии 6.7.0 Введена.

Код register_block_template() WP 7.1

wp-includes/block-template.php 
function register_block_template( $template_name, $args = array() ) {
	return WP_Block_Templates_Registry::get_instance()->register( $template_name, $args );
}

Редактор блоков (Gutenberg Гутенберг blocks)

FSE (block theme)