Шаблоны сайта
Шаблоны сайта позволяют блочным темам определять источники WordPress wp_template и
wp_template_part с помощью того же синтаксиса, в котором файлы используются в первую очередь, что и для страниц и паттернов Blockstudio.
Используйте шаблоны сайта, если хотите управлять макетом темы, который WordPress выбирает с помощью иерархии шаблонов редактора сайта: главная страница, отдельные записи, архивы, поиск, страницы 404, заголовки, подвалы и другие части шаблонов.
Страницы, паттерны или шаблоны сайта?
| Возможность | Создаёт | Лучше всего подходит для |
|---|---|---|
| Страницы | Записей или записей пользовательских типов | Реальных страниц с содержимым, страниц документации, целевых страниц и содержимого с маршрутами. |
| Паттерны | Паттерны блоков | Повторно используемых разделов, вставляемых редакторами. |
| Шаблоны сайта | wp_template и wp_template_part источников файлов |
Макета темы под управлением редактора сайта и иерархии шаблонов WordPress. |
Шаблоны сайта не создают обычные страницы. Они предоставляют источник файлов, который WordPress использует при разрешении шаблона блочной темы. Если пользователь настраивает шаблон в редакторе сайта, WordPress сохраняет эту настройку в базе данных, и она имеет приоритет над источником файлов, пока настройку не сбросят.
Структура папок
Поместите полные шаблоны в templates/, а части шаблонов — в parts/:
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
В каждой папке находится манифест и один файл-источник.
| Файл | Движок |
|---|---|
index.php |
Разметка блоков в стиле HTML, читается как есть (код PHP не выполняется) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
Разметка блоков в стиле HTML |
Если есть несколько исходных файлов, Blockstudio использует следующий порядок:
index.phpindex.blade.phpindex.twigindex.html
WordPress также рекурсивно обнаруживает файлы .html и обычно показывает вложенный шаблон index.html под слагом, полученным из пути, например header/index.
Если этот файл относится к манифесту Blockstudio, Blockstudio удаляет дубликат, полученный из пути, и показывает только объявленный в манифесте slug.
Вложенные нативные шаблоны .html без манифеста Blockstudio не меняются.
Исходный код один раз компилируется в нативную разметку блоков WordPress. Он не должен зависеть от текущего запроса или записи. Помещайте поведение времени выполнения внутрь динамических блоков.
template.json
template.json задаёт полный шаблон редактора сайта.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
Свойства
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
slug / name |
string |
Имя папки | Слаг шаблона WordPress. Используйте точные слаги иерархии, например front-page, single, archive-product или 404. |
title |
string |
Заголовок из слага | Отображаемый заголовок в редакторе сайта. |
description |
string |
"" |
Отображаемое описание в редакторе сайта. |
postTypes |
string[] |
[] |
Типы записей для пользовательских шаблонов. Для шаблонов основной иерархии это поле можно не указывать. |
source / template / file |
string |
Автоматически определяемый индексный файл | Необязательный путь к исходному файлу относительно папки шаблона. |
status |
string |
"publish" |
Статус шаблона. |
sync |
boolean |
false |
Зарезервировано для будущего переноса в базу данных. Пользовательские настройки никогда не перезаписываются в v1. |
meta |
object |
{} |
Пользовательские метаданные для вспомогательных API. Здесь также хранятся неизвестные ключи манифеста. |
Слаги шаблонов не имеют префикса. WordPress нужны точные имена для иерархии шаблонов:
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
part.json задаёт часть шаблона редактора сайта.
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
Свойства
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
slug / name |
string |
Имя папки | Слаг части шаблона WordPress. |
title |
string |
Заголовок из слага | Отображаемый заголовок в редакторе сайта. |
description |
string |
"" |
Отображаемое описание в редакторе сайта. |
area |
string |
"uncategorized" |
Область части шаблона. Часто используются значения header, footer и sidebar. |
source / template / file |
string |
Автоматически определяемый индексный файл | Необязательный путь к исходному файлу относительно папки части шаблона. |
status |
string |
"publish" |
Статус части шаблона. |
meta |
object |
{} |
Пользовательские метаданные для вспомогательных API. Здесь также хранятся неизвестные ключи манифеста. |
Создание разметки
В источниках шаблонов сайта используется тот же парсер, что и для страниц и паттернов:
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<p>This template is compiled from Blockstudio files.</p>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" />
</div>
Элемент <main> становится блоком core/group, который отображается как <main>, а его дочерние элементы, включая тег блока core/post-content, становятся внутренними блоками. Можно использовать:
- стандартные элементы HTML, например
<h1>,<p>,<ul>,<div>, а также элементы для структурирования разделов:<main>,<header>,<footer>,<article>и<aside> <block name="namespace/block"><bs:namespace-block>- настроенные префиксы тегов блоков
- блоки и компоненты Blockstudio
При отображении скомпилированного шаблона блоки частей шаблона получают атрибут активной темы от WordPress.
Настройки редактора сайта
Blockstudio предоставляет источник файлов. Настройки пользователя хранятся в WordPress.
Порядок поиска:
- Настройка в базе данных редактора сайта
- Файл
.htmlактивной нативной темы - Файловый источник Blockstudio
- Запасные варианты родительской темы или плагина
Когда пользователь сохраняет в редакторе сайта шаблон на основе файла Blockstudio, WordPress создаёт обычную запись базы данных wp_template или wp_template_part.
Эта сохранённая запись имеет приоритет над будущими изменениями файла. Сброс или удаление настройки снова показывает актуальный файловый источник.
Blockstudio не записывает изменения редактора сайта обратно в файлы в v1.
Производительность
Обнаружение шаблонов кэшируется на время запроса, а метаданные отслеживания файлов сохраняются. Изменение манифеста или исходного файла аннулирует кэшированное скомпилированное содержимое. Настройки из базы данных не перекрываются кэшем: WordPress по-прежнему сначала проверяет их.
Интеграции времени выполнения, объединяющие файлы из нескольких корневых каталогов, могут предоставлять для шаблонов и частей шаблонов логический источник обнаружения. Манифесты и выбранные исходные шаблоны могут находиться в разных физических корневых каталогах, сохраняя при этом единое логическое дерево темы.
PHP API
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();
$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');
$paths = Blockstudio\Site_Templates::get_paths();
Передайте явный список, чтобы считывать и компилировать только точные слаги, пути или пути к исходникам:
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
Если аргумент не указан, сохраняется полное поведение реестра. Пустой список не возвращает элементов. Запросы по стандартным слагам и путям сужают поиск до соответствующих каталогов; для пользовательских слагов манифеста может потребоваться сканирование метаданных, но посторонние источники всё равно не компилируются и не возвращаются.
Также доступны вспомогательные функции шаблонов:
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
Хуки
Полный список точек расширения шаблонов сайта:
| Хук | Тип | Описание |
|---|---|---|
blockstudio/site_templates/template_paths |
Фильтр | Изменяет корневые каталоги поиска полных шаблонов. |
blockstudio/site_templates/part_paths |
Фильтр | Изменяет корневые каталоги поиска частей шаблонов. |
blockstudio/site_templates/paths |
Фильтр | Изменяет оба списка путей как templates и parts. |
blockstudio/site_templates/template_candidates |
Фильтр | Изменяет кандидаты исходных файлов для манифеста. |
blockstudio/site_templates/templates |
Фильтр | Изменяет шаблоны, возвращаемые методом API реестра. |
blockstudio/site_templates/parts |
Фильтр | Изменяет части шаблонов, возвращаемые методом API реестра. |
blockstudio/site_templates/template_content |
Фильтр | Изменяет скомпилированный источник полного шаблона перед разбором. |
blockstudio/site_templates/part_content |
Фильтр | Изменяет скомпилированный источник части шаблона перед разбором. |
blockstudio/site_templates/parser |
Фильтр | Заменяет экземпляр Html_Parser для одного элемента. |
blockstudio/site_templates/source_compiled |
Действие | Выполняется непосредственно перед компиляцией одного выбранного источника. |
blockstudio/site_templates/discovered |
Действие | Выполняется после холодного цикла обнаружения и компиляции. |
blockstudio/site_templates/registered |
Действие | Выполняется после сохранения перестроенного реестра. |
Добавление или замена путей обнаружения:
add_filter('blockstudio/site_templates/template_paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
});
add_filter('blockstudio/site_templates/part_paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
});
add_filter('blockstudio/site_templates/paths', function ($paths) {
return $paths;
});
Фильтрация обнаруженных данных:
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
Фильтрация источника перед разбором:
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
return $content;
}, 10, 2);
add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
return $content;
}, 10, 2);
Изменение исходных кандидатов или парсера:
add_filter(
'blockstudio/site_templates/template_candidates',
function ($candidates, $directory, $manifest) {
$candidates[] = $directory . '/template.custom.php';
return $candidates;
},
10,
3
);
add_filter(
'blockstudio/site_templates/parser',
function ($parser, $item) {
return $parser;
},
10,
2
);
discovered и registered — действия жизненного цикла перестроения кэша. Они не запускаются при попадании в тёплый кэш реестра.