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

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

Тема на основі блоків описує макет у 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: верхній колонтитул, нижній колонтитул, окремий запис, архів Шаблони та частини шаблонів сайту
Сторінка з власним маршрутом, вміст якої зберігається у файлах Сторінки з файлів
Багаторазовий розділ, який редактори вставляють у вміст Візерунки

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

Наступні кроки