Шаблоны и части редактора сайта из файлов
Блочная тема описывает структуру в templates/*.html и parts/*.html:
файлах с сериализованными комментариями блоков, например
<!-- wp:template-part {"slug":"header"} /-->. Никто не любит писать их
вручную, поэтому обычно их создают в редакторе сайта и экспортируют. Это работает,
пока два человека не отредактируют один шаблон или рецензенту не придется читать различия в экранированном JSON в комментариях HTML.
Blockstudio позволяет создавать те же шаблоны так же, как страницы на основе файлов:
в папке с небольшим манифестом JSON и исходным файлом с разметкой в стиле HTML, обычными элементами, тегами <block> и собственными блоками Blockstudio.
Blockstudio компилирует исходный код в нативную разметку блоков и передает ее WordPress как файл темы. Редактор сайта работает как и прежде: пользователи могут настраивать шаблон, а после сброса восстанавливается версия из файла.
В этом руководстве мы создадим части для верхнего и нижнего колонтитулов, шаблоны главной страницы и отдельной записи, а также собственный шаблон, который редакторы смогут выбирать для страниц, а затем покажем, как их обрабатывает WordPress.
Структура папок
Шаблоны размещаются в templates/, части шаблонов — в parts/. Каждый из них представляет собой папку с манифестом и одним исходным файлом:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
Это те же папки templates/ и parts/, которые WordPress использует для блочной темы. Сначала Blockstudio проверяет активную тему, затем родительскую. Папки с файлами template.json или part.json считаются источниками Blockstudio; расположенные рядом обычные файлы .html остаются нативными шаблонами WordPress.
Исходным файлом может быть index.php, index.blade.php, index.twig или index.html — проверяются они именно в таком порядке. Для Twig требуется Timber, а для Blade — пакет рендерера, как описано в разделе Движки шаблонов.
Шаг 1: Часть верхнего колонтитула
Каждой части нужен part.json. Свойство area указывает редактору сайта, где разместить эту часть:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
В исходном коде используется тот же синтаксис, что и для страниц Blockstudio и паттернов. Элемент <div> становится блоком группы, атрибуты — атрибутами блока, а элементы <block> создают соответствующие зарегистрированные блоки:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudio компилирует его в такую разметку блоков:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
Именно такую разметку вам пришлось бы написать вручную. Собственные блоки работают так же: <block name="acme/announcement" />, тег <bs:acme-announcement /> или настроенный префикс тега компилируются в комментарий блока для этого блока.
Шаг 2: Часть нижнего колонтитула
Часть может состоять всего из одного абзаца. Здесь используется index.html, чтобы показать: исходный код — это разметка, а не программа:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
Результат компиляции: <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
Шаг 3: Шаблоны главной страницы и отдельной записи
В шаблонах используется template.json. Значение slug должно точно соответствовать имени шаблона в иерархии WordPress, например front-page, single, page, archive, 404 или single-product. Blockstudio никогда не добавляется в начало этого значения.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Шаблон отдельной записи имеет ту же структуру, но использует блоки записей:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
Скомпилированный шаблон отдельной записи:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main> стал блоком группы с tagName: "main", а блоки частей шаблона ссылаются на части из шагов 1 и 2 по слагу. Когда WordPress отображает шаблон, эти ссылки разрешаются в части из файлов, поэтому вывод главной страницы начинается с <header class="wp-block-template-part">, содержащего название сайта и навигацию, и заканчивается <footer class="wp-block-template-part"> с абзацем нижнего колонтитула.
Шаг 4: Собственный шаблон для страниц
Шаблоны, слаг которых не входит в иерархию, называются собственными. Укажите типы записей, к которым они применяются, с помощью postTypes — тогда редакторы смогут выбрать их в списке шаблонов:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) теперь включает page-landing, а объект шаблона содержит post_types: ["page"].
Исходные файлы компилируются один раз
Исходный код считывается и один раз компилируется в разметку блоков, а не при каждом запросе. На этом этапе нет текущей записи и контекста запроса. index.php обрабатывается как разметка: код PHP в нем не выполняется, поэтому <?php echo get_bloginfo( 'name' ); ?> компилируется в пустую строку. Всё, что зависит от запроса, должно находиться в блоке, который отображается во время выполнения: core/site-title вместо выведенного названия сайта, core/post-title вместо the_title() или собственного динамического блока Blockstudio.
Результаты компиляции кэшируются вместе с метаданными для отслеживания файлов. При изменении манифеста или исходного файла кэш соответствующего элемента сбрасывается, поэтому следующий запрос увидит обновление без отдельного этапа сборки.
Как WordPress находит файлы
Blockstudio подключается к тем же механизмам поиска, которые WordPress использует для шаблонов тем. В get_block_templates() шаблоны из файлов отображаются с source: "theme" и origin: "theme", как и нативные файлы темы, а get_block_template( 'acme//header', 'wp_template_part' ) возвращает часть верхнего колонтитула вместе с area.
Порядок поиска:
- Настройка редактора сайта, сохраненная в базе данных.
- Нативный файл
.htmlв активной теме. - Исходный файл Blockstudio.
- Запасные варианты из родительской темы или плагина.
Такой порядок сохраняет привычный процесс работы в редакторе сайта. Когда пользователь редактирует нижний колонтитул и сохраняет изменения, WordPress сохраняет запись wp_template_part, а get_block_template() возвращает эту настройку вместе с source: "custom". Пока существует эта настройка, последующие изменения в parts/footer/index.html не отображаются. После сброса части пользователем или удаления записи поиск возвращается к файлу и использует его последнюю скомпилированную версию.
Blockstudio не сохраняет изменения из редактора сайта обратно в файлы. Если изменение должно стать новым значением по умолчанию, перенесите его в исходный файл и сбросьте настройку.
Вложенные index.html и слаги
WordPress рекурсивно находит файлы .html в templates/ и parts/. Поэтому папка с манифестом, в которой используется index.html, например parts/footer/index.html, также появится как нативная часть слагом, полученным из пути: footer/index. Поскольку Blockstudio 7.6.6, часть index.html, управляемая манифестом, доступна только под объявленным слагом, поэтому в редакторе сайта отображается один нижний колонтитул, а не два. Вложенные файлы .html без манифеста остаются без изменений.
Проверка шаблонов из PHP
Класс Blockstudio\Site_Templates считывает и компилирует исходные файлы, что полезно при тестировании и проверках перед развертыванием:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
Каждый элемент содержит slug, title, description, type (wp_template или wp_template_part), status, source_type, postTypes для шаблонов или area для частей, meta и скомпилированный content. Передайте список, чтобы скомпилировать только выбранные элементы, а сведения об ошибках для них получите с помощью selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
Добавление других папок
Чтобы отделить исходные файлы Blockstudio от нативных шаблонов или поставлять их в составе плагина, добавьте корневые каталоги для поиска с фильтрами:
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;
} );
Фильтры blockstudio/site_templates/template_content и part_content изменяют исходный файл перед разбором, а blockstudio/site_templates/parser заменяет анализатор для отдельного элемента. Полный список приведен в таблице Перехватчики шаблонов сайта.
Что и когда использовать
| Что нужно | Используйте |
|---|---|
| Макет темы WordPress для URL: верхний и нижний колонтитулы, отдельная запись, архив | Шаблоны и части сайта |
| Страница с доступом по маршруту, содержимое которой хранится в файлах | Страницы на основе файлов |
| Повторно используемый раздел, который редакторы вставляют в содержимое | Паттерны |
Шаблоны не создают записи — их создают страницы. Например, раздел документации представляет собой коллекцию страниц, записи которой отображаются с помощью шаблона, который по-прежнему можно создать здесь.
Следующие шаги
- Справочник по шаблонам сайта: все свойства манифеста, объект PHP API и все перехватчики.
- Обзор страниц и паттернов: анализатор HTML, теги блоков и сопоставление элементов, используемые в исходных файлах шаблонов.
- Создание сайта документации: коллекции страниц с помощью Markdown, загрузчиков и макетов.