Шаблони сайту
Шаблони сайту дають змогу блоковим темам визначати 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 — це дії життєвого циклу перебудови кешу. Вони не виконуються під час влучання в кеш теплого реєстру.