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

Шаблоны сайта

Шаблоны сайта позволяют блочным темам определять источники WordPress wp_template и wp_template_part с помощью того же синтаксиса, в котором файлы используются в первую очередь, что и для страниц и паттернов Blockstudio.

Используйте шаблоны сайта, если хотите управлять макетом темы, который WordPress выбирает с помощью иерархии шаблонов редактора сайта: главная страница, отдельные записи, архивы, поиск, страницы 404, заголовки, подвалы и другие части шаблонов.

Страницы, паттерны или шаблоны сайта?

Возможность Создаёт Лучше всего подходит для
Страницы Записей или записей пользовательских типов Реальных страниц с содержимым, страниц документации, целевых страниц и содержимого с маршрутами.
Паттерны Паттерны блоков Повторно используемых разделов, вставляемых редакторами.
Шаблоны сайта wp_template и wp_template_part источников файлов Макета темы под управлением редактора сайта и иерархии шаблонов WordPress.

Шаблоны сайта не создают обычные страницы. Они предоставляют источник файлов, который WordPress использует при разрешении шаблона блочной темы. Если пользователь настраивает шаблон в редакторе сайта, WordPress сохраняет эту настройку в базе данных, и она имеет приоритет над источником файлов, пока настройку не сбросят.

Структура папок

Поместите полные шаблоны в templates/, а части шаблонов — в parts/:

Text
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 использует следующий порядок:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPress также рекурсивно обнаруживает файлы .html и обычно показывает вложенный шаблон index.html под слагом, полученным из пути, например header/index. Если этот файл относится к манифесту Blockstudio, Blockstudio удаляет дубликат, полученный из пути, и показывает только объявленный в манифесте slug. Вложенные нативные шаблоны .html без манифеста Blockstudio не меняются.

Исходный код один раз компилируется в нативную разметку блоков WordPress. Он не должен зависеть от текущего запроса или записи. Помещайте поведение времени выполнения внутрь динамических блоков.

template.json

template.json задаёт полный шаблон редактора сайта.

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 нужны точные имена для иерархии шаблонов:

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

part.json задаёт часть шаблона редактора сайта.

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. Здесь также хранятся неизвестные ключи манифеста.

Создание разметки

В источниках шаблонов сайта используется тот же парсер, что и для страниц и паттернов:

PHP
<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.

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

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

Когда пользователь сохраняет в редакторе сайта шаблон на основе файла Blockstudio, WordPress создаёт обычную запись базы данных wp_template или wp_template_part. Эта сохранённая запись имеет приоритет над будущими изменениями файла. Сброс или удаление настройки снова показывает актуальный файловый источник.

Blockstudio не записывает изменения редактора сайта обратно в файлы в v1.

Производительность

Обнаружение шаблонов кэшируется на время запроса, а метаданные отслеживания файлов сохраняются. Изменение манифеста или исходного файла аннулирует кэшированное скомпилированное содержимое. Настройки из базы данных не перекрываются кэшем: WordPress по-прежнему сначала проверяет их.

Интеграции времени выполнения, объединяющие файлы из нескольких корневых каталогов, могут предоставлять для шаблонов и частей шаблонов логический источник обнаружения. Манифесты и выбранные исходные шаблоны могут находиться в разных физических корневых каталогах, сохраняя при этом единое логическое дерево темы.

PHP API

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

Передайте явный список, чтобы считывать и компилировать только точные слаги, пути или пути к исходникам:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

Если аргумент не указан, сохраняется полное поведение реестра. Пустой список не возвращает элементов. Запросы по стандартным слагам и путям сужают поиск до соответствующих каталогов; для пользовательских слагов манифеста может потребоваться сканирование метаданных, но посторонние источники всё равно не компилируются и не возвращаются.

Также доступны вспомогательные функции шаблонов:

PHP
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 Действие Выполняется после сохранения перестроенного реестра.

Добавление или замена путей обнаружения:

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;
});

add_filter('blockstudio/site_templates/paths', function ($paths) {
    return $paths;
});

Фильтрация обнаруженных данных:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

Фильтрация источника перед разбором:

PHP
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);

Изменение исходных кандидатов или парсера:

PHP
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 — действия жизненного цикла перестроения кэша. Они не запускаются при попадании в тёплый кэш реестра.