Перейти до вмісту

Шаблони сайту

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