Перейти к содержимому

Шаблоны и части редактора сайта из файлов

Блочная тема описывает структуру в 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 указывает редактору сайта, где разместить эту часть:

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Site header with logo and navigation",
  "area": "header"
}

В исходном коде используется тот же синтаксис, что и для страниц Blockstudio и паттернов. Элемент <div> становится блоком группы, атрибуты — атрибутами блока, а элементы <block> создают соответствующие зарегистрированные блоки:

PHP
<div layout='{"type":"flex","justifyContent":"space-between"}'>
  <block name="core/site-title" />
  <block name="core/navigation" overlayMenu="mobile" />
</div>

Blockstudio компилирует его в такую разметку блоков:

HTML
<!-- 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 /> или настроенный префикс тега компилируются в комментарий блока для этого блока.

Часть может состоять всего из одного абзаца. Здесь используется index.html, чтобы показать: исходный код — это разметка, а не программа:

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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 никогда не добавляется в начало этого значения.

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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" />

Шаблон отдельной записи имеет ту же структуру, но использует блоки записей:

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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" />

Скомпилированный шаблон отдельной записи:

HTML
<!-- 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 — тогда редакторы смогут выбрать их в списке шаблонов:

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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.

Порядок поиска:

  1. Настройка редактора сайта, сохраненная в базе данных.
  2. Нативный файл .html в активной теме.
  3. Исходный файл Blockstudio.
  4. Запасные варианты из родительской темы или плагина.

Такой порядок сохраняет привычный процесс работы в редакторе сайта. Когда пользователь редактирует нижний колонтитул и сохраняет изменения, 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 считывает и компилирует исходные файлы, что полезно при тестировании и проверках перед развертыванием:

PHP
$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():

PHP
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors   = Blockstudio\Site_Templates::selection_errors( 'templates' );

Добавление других папок

Чтобы отделить исходные файлы Blockstudio от нативных шаблонов или поставлять их в составе плагина, добавьте корневые каталоги для поиска с фильтрами:

PHP
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: верхний и нижний колонтитулы, отдельная запись, архив Шаблоны и части сайта
Страница с доступом по маршруту, содержимое которой хранится в файлах Страницы на основе файлов
Повторно используемый раздел, который редакторы вставляют в содержимое Паттерны

Шаблоны не создают записи — их создают страницы. Например, раздел документации представляет собой коллекцию страниц, записи которой отображаются с помощью шаблона, который по-прежнему можно создать здесь.

Следующие шаги