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

Сторінки

Сторінки — це шаблони на основі файлів, які синхронізуються з базою даних WordPress як записи. Синхронізація виконується явно: запустіть wp bs pages sync або викличте сторінки API, коли потрібно застосувати зміни джерела. Завантаження інтерфейсу сайту або адмінпанелі WordPress ніколи не виконує повне виявлення сторінок і не змінює записи сторінок.

Сторінки можна визначати як одну папку page.json, як окремі Markdown або як колекцію з маніфестом pages.json. Колекції корисні для документації, баз знань, бібліотек цільових сторінок або будь-яких наборів вкладених сторінок, які потрібно генерувати з файлів.

page.json

Щоб визначити сторінку через JSON, додайте файл конфігурації page.json:

JSON
{
  "name": "about",
  "title": "About Us",
  "slug": "about-us",
  "postType": "page",
  "postStatus": "publish",
  "templateLock": "all"
}

Властивості

Властивість Тип Значення за замовчуванням Опис
name string обов’язково Унікальний ідентифікатор сторінки
title string Автоматично з назви Заголовок сторінки
slug string Такий самий, як назва URL-слаґ сторінки
path string "." Логічний шлях у колекції
order integer 0 Порядок у меню для синхронізованого запису
postType string "page" WordPress тип запису
postStatus string "draft" Статус для нових записів (publish, draft, pending, private)
postId integer – Закріпити сторінку за певним ID запису WordPress
blockEditingMode string – Режим редагування блоків: "default", "contentOnly" або "disabled"
templateLock string|false "all" Режим блокування: "all", "insert", "contentOnly" або false
templateFor string|null null Задати шаблон за замовчуванням для типу запису
sync boolean true Чи може звичайне явне узгодження створювати або оновлювати запис
render string|object|false – Відобразити сторінку за допомогою зареєстрованого засобу рендерингу сторінок (див. Сторінки компонентів)

У page.json, frontmatter і записах завантажувача розпізнаються такі ключі: blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock і title. Будь-який ключ, якого немає в списку вище, зберігається в масиві meta сторінки.

Джерела вмісту

Визначення сторінки задає, який запис WordPress має існувати. Джерело вмісту визначає, яку розмітку блоків записати в цей запис.

Якщо папка сторінки містить page.json, Blockstudio шукає сусідній файл джерела в такому порядку:

Файл Використання
index.php Розмітка блоків на кшталт HTML, читається як є (код PHP не виконується)
index.blade.php Вміст шаблону Blade
index.twig Вміст шаблону Twig
index.md Вміст Markdown

page.json також може містити вбудований markdown або html замість посилання на сусідній файл:

JSON
{
  "name": "intro",
  "title": "Intro",
  "markdown": "# Intro\n\nThis page is generated from inline markdown."
}
JSON
{
  "name": "notice",
  "title": "Notice",
  "html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}

Колекції додають ще два режими джерел:

  • Файли Markdown, знайдені безпосередньо в дереві колекції.
  • Записи завантажувача, повернуті з loader.php.

Записи завантажувача можуть використовувати markdown, html або content разом із contentType. Вони також можуть вказувати на локальний file або template. Тип файлів і шаблонів визначається за розширенням, якщо contentType не задано явно.

Підтримувані значення contentType: php, blade, twig, markdown і html. Спочатку Markdown перетворюється на HTML, а потім розбирається на нативні блоки WordPress. Джерела PHP, Blade, Twig і HTML проходять через звичайний парсер сторінок Blockstudio.

Класи в основних блоках

class в елементі HTML, зіставленому з основним блоком, стає його className. Для явного тегу основного блоку можна безпосередньо використовувати className. Обидві форми зберігають класи збереженої обгортки блоку разом із класами, які генерує WordPress:

HTML
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
  <h2 class="title">Feature</h2>
</block>

Якщо присутні обидві властивості, пріоритет має className. Це перетворення застосовується лише до основних блоків: зіставлення власного блоку залишає його поле class без змін. Класи стилю кнопки, як-от is-style-outline, належать обгортці кнопки, а не її посиланню.

Запустіть wp bs pages sync, щоб застосувати виправлення парсера до раніше синхронізованих сторінок. Оновлення парсера розпізнаються під час наступної явної синхронізації без редагування вихідного файла. Заблоковані сторінки та сторінки з sync: false зберігають звичайний захист; запити фронтенду ніколи не запускають цю синхронізацію.

Серіалізовані блоки WordPress

Джерела сторінок і шаблонів також можуть містити серіалізовані блоки, скопійовані з редактора коду WordPress:

HTML
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->

Якщо джерело містить роздільник блоку <!-- wp:... -->, Blockstudio використовує власний парсер блоків WordPress для всього джерела. Атрибути, вкладені блоки, динамічні блоки, як-от Query Loop, і блоки Blockstudio зберігають свою серіалізовану структуру. HTML поза коментарями блоків залишаються власним довільним вмістом HTML; їх не перетворюють на додаткові блоки. Не змішуйте теги блоків Blockstudio HTML із цим форматом, очікуючи, що їх буде перетворено. Звичайні коментарі HTML не вмикають режим серіалізованих блоків.

Сторінки Markdown

Використовуйте Markdown, коли текст має зберігатися у файлах, але після синхронізації залишатися редагованим вмістом блоків WordPress. Під час синхронізації джерело Markdown перетворюється на розмітку блоків. У синхронізованому записі зберігаються блоки, а не вихідний текст Markdown.

Markdown можна використовувати трьома способами:

Джерело Потрібен frontmatter? Примітки
Окремий pages/example/index.md Так Frontmatter містить ідентифікаційні дані сторінки.
page.json разом із index.md Ні page.json визначає сторінку, а Markdown містить вміст.
Markdown у колекції Ні Колекція визначає name і path за розташуванням файлу.

Окремий index.md без frontmatter пропускається, оскільки Blockstudio не має ідентифікатора сторінки для синхронізації. Для Markdown у колекції frontmatter не потрібен, бо цей ідентифікатор визначають маніфест колекції та шлях до файлу.

Markdown
---
name: about
title: About
slug: about
postStatus: publish
---

# About

This Markdown content is synced as native WordPress blocks.

Також можна поєднати page.json із index.md. У такому разі page.json визначає сторінку, а index.md містить вміст. Frontmatter у index.md перевизначає відповідні значення page.json.

JSON
{
  "name": "docs-reference",
  "title": "Reference",
  "path": "reference",
  "sync": true
}
Markdown
---
title: API Reference
order: 20
---

# Reference

This page uses `page.json` with Markdown content.

Для колекційного Markdown шлях до файлу стає логічним шляхом сторінки, якщо frontmatter його не перевизначає:

Файл Шлях за замовчуванням
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Невідомі ключі frontmatter зберігаються в масиві meta сторінки. Це дає змогу додавати дані, як-от section або description, і читати їх із PHP API.

Markdown розбирається як GitHub Flavored Markdown. Дозволено необроблений HTML, небезпечні посилання вилучаються, а заголовки без явного ID отримують стабільний ідентифікатор. Для вкладеного frontmatter YAML потрібен вбудований парсер YAML.

Необроблений Markdown

Джерела файлів Markdown можуть надавати оригінальний вихідний Markdown для зовнішніх інструментів і споживачів документації. Вбудований Markdown не має вихідного файлу, тому синхронізується в блоки, але не повертає необроблену відповідь .md.

Запитуйте сторінку з суфіксом .md, наприклад https://example.com/docs/reference.md. Або передайте заголовок Accept: text/markdown у звичайному URL сторінки:

Командна оболонка
curl -H "Accept: text/markdown" https://example.com/docs/reference/

Frontmatter вилучається з відповіді. Успішні відповіді з необробленим Markdown повертають заголовки Content-Type: text/markdown і X-Robots-Tag: noindex, а також канонічний заголовок Link для сторінки HTML. Для відсутніх маршрутів .md повертається справжній 404.

Узгодження працює зі статичним попереднім рендерингом: запит, у заголовку Accept якого міститься text/markdown, ніколи не обслуговується зі сховища попередньо згенерованих сторінок чи плагіна ранньої відповіді, тож він доходить до WordPress і обробника Markdown. Попередньо згенеровані відповіді HTML, HTML сторінки, яка також узгоджує Markdown, і Markdown, отримана через Accept, надсилають Vary: Accept, тож кеші, які враховують Vary, зберігають їх окремо. Для CDN, який формує ключ кешу лише за URL, потрібно окреме правило обходу кешу для таких запитів. Pages::negotiates_markdown( $post_id ) повідомляє, чи відповідає сторінка на запити Markdown.

У колекції Markdown для необробленого Markdown зберігається та сама структура URL:

URL сторінки Необроблений Markdown URL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

Вимкніть відповіді з необробленим Markdown за допомогою фільтра blockstudio/pages/serve_markdown:

PHP
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );

Запит .md URL, який не відповідає сторінці на основі Markdown, повертає 404, лише якщо шлях належить до колекції сторінок. Поза всіма колекціями Blockstudio не перехоплює запит, залишаючи його для обробки WordPress та іншими плагінами.

Сторінки компонентів

Сторінка компонента відображається засобом рендерингу сторінок, а не зберігається як блоки. Blockstudio не постачається із засобом рендерингу. Тема або плагін реєструє такий засіб для оброблюваних ним файлів запису, наприклад засіб рендерингу React для page.tsx, а Blockstudio викликає його, передаючи сторінку, запис WordPress і вміст відрендереного слота.

Text
pages/legal-notice/
  page.json
  page.tsx
  data.php
JSON
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

render задається явно. Каталог із index.php і page.tsx, але без render, залишається звичайною сторінкою, тож додавання засобу рендерингу ніколи не призведе до повторного відображення наявної сторінки. Форми запису:

Значення Значення
"page.tsx" Лише запис, без завантажувача даних
{ "entry": "page.tsx", "data": "data.php" } Запис і завантажувач даних
{ "entry": "page.tsx", "renderer": "react" } Запис із явно вказаним ідентифікатором засобу рендерингу
false Без засобу рендерингу, навіть якщо його вказано як типовий для колекції

Шляхи визначаються відносно каталогу сторінки або відносно кореня колекції для записів завантажувача. Вони мають залишатися в межах джерела виявлення, якщо blockstudio/pages/allow_external_loader_path не дозволяє інше. Якщо renderer не задано, використовується засіб рендерингу, якому відповідає розширення файлу запису. Якщо render указує на відсутній файл запису чи даних, невідомий засіб рендерингу або розширення, яке не обробляє жоден засіб рендерингу, виникає помилка виявлення, через яку узгодження завершується до видалення будь-яких елементів.

Що зберігає синхронізація

Синхронізація зберігає один блок blockstudio/page. Якщо в каталозі сторінки також є джерело index.*, його розбирають як будь-яке джерело сторінки, і його вміст стає внутрішніми блоками блока — його слотом:

HTML
<!-- wp:blockstudio/page /-->

<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->

Зберігайте в слоті вміст, яким керує WordPress, наприклад шорткоди. Якщо джерело складається лише з одного шорткоду, як-от [download_checkout], його зберігають як блок core/shortcode, тож навколо його виводу не додається абзац. Він залишається в post_content, тому його бачать перевірки has_shortcode(), блоки слота з ключами об’єднуються зі змінами в редакторі так само, як вкладені блоки з ключами, а do_shortcode розгортає шорткоди один раз із типовим пріоритетом the_content, після того як засіб рендерингу обгорнув їх.

Визначення рендерингу зберігається разом із записом як переносні шляхи theme:. Відбиток сторінки охоплює визначення, а не байти файлу запису чи завантажувача даних: зміни в page.tsx або data.php не змінюють запис і стають доступними відвідувачам через рендеринг і граф статичного попереднього рендерингу, який фіксує файл запису, завантажувач даних і кожен файл, про який повідомляє засіб рендерингу.

Реєстрація засобу рендерингу

Реєструйте засоби рендерингу на дії blockstudio/pages/renderers. Вона виконується один раз за запит, до першого виявлення або рендерингу, тож wp bs pages sync і запити до фронтенду бачать той самий реєстр.

PHP
add_action(
	'blockstudio/pages/renderers',
	static function (): void {
		Blockstudio\Page_Renderers::register(
			'react',
			array(
				'extensions' => array( 'tsx' ),
				'layouts'    => array( 'layout.tsx' ),
				'render'     => 'my_theme_render_page',
			)
		);
	}
);

Ідентифікатори засобів рендерингу пишуться малими літерами. Одне розширення або назва макета може належати лише одному засобу рендерингу, а layout.php залишається власним макетом Blockstudio. Функція отримує один запит:

Ключ Значення
kind page або layout для макета засобу рендерингу
renderer Ідентифікатор засобу рендерингу
entry Абсолютний шлях до файлу запису
data Абсолютний шлях до завантажувача даних або null
page Канонічні дані сторінки, зокрема meta
post_id ID запису WordPress
slot Відрендерений вміст слота або вміст сторінки для макета
context frontend, rest, feed або cli

Він повертає HTML, файли, прочитані під час рендерингу, і необов’язкові ресурси:

PHP
function my_theme_render_page( array $request ): array {
	return array(
		'html'         => '<main>...</main>',
		'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
		'assets'       => array( array( 'path' => '/abs/path/to/page.js' ) ),
	);
}

context надходить із типу запиту, а не від відвідувача, тож renderer не може порушити паритет байтів для авторизованих і анонімних користувачів, зчитуючи його. Якщо renderer завершується з помилкою, він її викидає: сторінка не відображає порожній вміст. У попередньому перегляді редактора REST блок натомість показує помилку як сповіщення. Після успішного рендерингу дія blockstudio/pages/rendered отримує сторінку, HTML та її залежності.

assets перелічує файли скриптів і стилів, потрібні сторінці. До них застосовується обробка ресурсів блоків (домовленість *.inline.*, ES-модулі, мініфікація та ?ver), а сторінка виводить їх один раз через той самий буфер, що й ресурси блоків, тож попередньо відрендерена сторінка містить їх. Ресурс може встановити version, щоб замінити значення ?ver. Код поза renderer може використовувати той самий канал через Blockstudio\Assets::register_owner(), який повертає коментар-маркер для виведення.

Редактор

У редакторі blockstudio/page показує попередній перегляд сторінки, відрендереної на сервері, зі слотом як внутрішніми блоками, які відповідають templateLock сторінки. Блок не можна вставити, дублювати або вкласти в інший блок.

Колекції сторінок

Колекція — це папка з маніфестом pages.json. Вона об’єднує багато джерел сторінок під одним слагом колекції, застосовує типові значення, підтримує вкладені шляхи та може автоматично реєструвати окремий тип запису.

Код
pages/
  docs/
    pages.json
    layout.php
    index.md
    guide/
      install/
        index.md
    reference/
      page.json
      index.md
    loader.php
JSON
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "postTypeArgs": {
    "label": "Docs",
    "rewrite": {
      "slug": "docs"
    },
    "supports": ["title", "editor", "page-attributes"]
  },
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}
Властивість Тип Опис
collection / slug / name string Слаг колекції. collection — найчіткіша форма, яка стає основою публічного URL.
title string Зрозуміла людині назва колекції.
postType string Тип запису для згенерованих сторінок. За замовчуванням — page. Якщо його не існує, Blockstudio реєструє його.
postTypeArgs object Аргументи, передані до register_post_type(), коли Blockstudio реєструє тип запису колекції.
defaults object Типові властивості сторінки, що застосовуються до кожної сторінки колекції. Типове render застосовується до сторінки лише тоді, коли її запис є в каталозі сторінок.
scope string collection (типово) або site. Див. Колекції сайтів.
meta object Власні метадані колекції. Невідомі ключі маніфесту також зберігаються в meta.

Шляхи сторінок у колекції є логічними. Сторінка з path: "guide/install" синхронізується як дочірня сторінка guide, а guide — як дочірня сторінка кореня колекції, якщо ці батьківські сторінки існують.

Якщо в ієрархічній колекції є вкладена сторінка, але джерела проміжної батьківської сторінки немає, Blockstudio створює для цього шляху порожню контейнерну сторінку, щоб зберегти повноту ієрархії WordPress. Для неієрархічних типів записів (без підтримки батьківських записів page-attributes) порожні контейнери не створюються. Маршрутизація виконується за збереженим шляхом колекції, тому вкладені шляхи, як-от guide/install і setup/install, можуть співіснувати, навіть якщо обидва закінчуються на install.

Типи записів колекції та URL-адреси

Установіть postType у маніфесті колекції, щоб синхронізувати всі її сторінки з цим типом запису. Повторювати те саме значення в defaults не потрібно. Для окремих сторінок значення postType усе ще можна перевизначити у frontmatter або page.json.

Якщо типу запису ще немає, Blockstudio реєструє його через show_in_rest: true із редактором, подібним до редактора сторінок, і слагом колекції як основою загальнодоступного URL. Аргументи реєстрації можна перевизначити через postTypeArgs. Правила перезапису URL для типів записів колекцій оновлюються автоматично, коли змінюються зареєстровані типи записів колекцій або аргументи перезапису, тож повторно зберігати постійні посилання WordPress не потрібно.

URL-адреси колекцій складаються зі слага колекції та логічного шляху кожної сторінки path:

Шлях до джерела Публічний URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Ця модель URL працює як з ієрархічними, так і з неієрархічними типами записів колекцій. Blockstudio також перенаправляє URL із подвоєнням, як-от /docs/docs/ або /docs/docs/getting-started/, на канонічний URL.

Сторінки колекцій надають необроблений Markdown за тими самими URL (див. Необроблений Markdown).

Якщо змінити колекцію з postType: "page" на власний тип запису, Blockstudio перенесе вже синхронізовані записи колекції на місці, якщо збережена ідентичність їхньої сторінки збігається. Це зберігає ID записів, метадані та наявний вміст і запобігає дублюванню записів зі старим типом. Застарілі записи колекції очищуються для всіх статусів записів відповідно до фільтра blockstudio/pages/orphan_action.

Колекції сайтів

Маніфест із "scope": "site" об’єднує всі сторінки під ним, не перетворюючи їх на сторінки колекції. Використовуйте його в корені дерева сторінок сайту, щоб застосувати спільні типові значення та перелічити сторінки сайту за допомогою blockstudio_page_tree( 'my-site' ).

JSON
{
  "collection": "my-site",
  "title": "My Site",
  "scope": "site",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "all",
    "render": { "entry": "page.tsx", "data": "data.php" }
  }
}

Сторінки колекції сайту зберігають ту саму ідентичність, яку мали без маніфесту, тож додавання його до наявного дерева не змінює рядки записів і нічого не створює та не видаляє:

  • Ключі залишаються глобальними: Pages::get_page( 'home' ) і збережені ключі сторінок збігаються.
  • URL сторінок залишаються WordPress. Правила перезапису колекції, фільтр постійних посилань і перенаправлення з подвоєним URL не застосовуються; порожні сторінки-контейнери не генеруються.
  • Логічні шляхи, слаги, батьківські сторінки та ідентичності джерел відповідають окремим сторінкам, а макети визначаються за найближчим предком.
  • Вкладені маніфести pages.json зберігають власні колекції, а їхні піддерева не входять до колекції сайту.
  • Типові значення застосовуються до кожної сторінки окремо: типове render застосовується лише до сторінок, запис яких є в каталозі, тож сторінки зі шорткодами та Markdown зберігають свої джерела.

Завантажувачі колекцій

Колекції можуть містити довірений локальний loader.php. Використовуйте його, коли сторінки колекції надходять з іншого локального джерела, наприклад із зовнішньої папки документації, пакета або згенерованого маніфесту.

Завантажувач запускається під час явного пошуку сторінок і синхронізації. Він має працювати детерміновано й локально. Не завантажуйте віддалений вміст із loader.php, оскільки це створило б залежність синхронізації розгортання від цього сервісу.

PHP
<?php

return array(
  'meta' => array(
    'source' => 'loader',
  ),
  'paths' => array(
    __DIR__ . '/external-docs',
    array(
      'path' => __DIR__ . '/cli-docs',
      'prefix' => 'cli',
      'meta' => array(
        'doc_set' => 'cli',
      ),
    ),
  ),
  'pages' => array(
    array(
      'name' => 'docs-api',
      'title' => 'API',
      'path' => 'api',
      'content' => "# API\n\nGenerated markdown content.",
      'contentType' => 'markdown',
    ),
    array(
      'name' => 'docs-template',
      'title' => 'Template',
      'path' => 'template',
      'file' => __DIR__ . '/template.md',
    ),
  ),
);

Завантажувач може повертати масив із ключами pages, meta і paths:

Ключ Опис
pages Список масивів сторінок. Кожна сторінка підтримує ті самі розпізнавані ключі, що й page.json та Markdown у frontmatter.
meta Метадані, об’єднані з масивом meta кожної сторінки, створеної завантажувачем.
paths Додаткові локальні каталоги для пошуку в межах цієї колекції. Записи можуть бути рядками або об’єктами шляхів.
render Визначення рендерингу для кожної сторінки Markdown, знайденої в paths.

Для стислості завантажувач може повертати звичайний список масивів сторінок.

Елементи сторінок завантажувача можуть надавати вміст такими способами:

Форма Опис
markdown Вбудований вміст Markdown.
html Вбудований вміст HTML.
content + contentType Загальний вбудований вміст. contentType має визначатися як markdown або html.
file Джерело з локального файла. Тип визначається за розширенням, якщо не задано contentType.
template Псевдонім для file.

Посилання на файли в завантажувачі можуть вказувати на джерела PHP, Blade, Twig, Markdown або HTML. Відносні шляхи визначаються від кореня колекції. Абсолютні шляхи та шляхи поза коренем колекції дозволені лише тоді, коли це дозволяє фільтр blockstudio/pages/allow_external_loader_path.

Для сторінок завантажувача типовим є generated: true. Коли згенерована сторінка завантажувача зникає з результатів, Blockstudio під час наступної синхронізації вважає відповідний синхронізований запис сиротою й очищує його відповідно до фільтра blockstudio/pages/orphan_action.

Каталоги, зазначені в paths, скануються так само, як звичайні папки колекції. Вони можуть містити файли Markdown або папки page.json. Якщо ці шляхи розташовані поза коренем колекції, до них застосовується той самий фільтр зовнішніх шляхів.

Використовуйте рядковий елемент, якщо зовнішній каталог має зберігати власні логічні шляхи. Використовуйте об’єктний елемент, щоб підключити каталог із префіксом шляху колекції:

PHP
'paths' => array(
  array(
    'path' => __DIR__ . '/cli-docs',
    'prefix' => 'cli',
    'meta' => array(
      'doc_set' => 'cli',
    ),
  ),
),

За такої конфігурації cli-docs/index.md стає path: "cli", а cli-docs/getting-started.md стає path: "cli/getting-started" у колекції. Префікси також запобігають конфліктам імен згенерованих сторінок, тож у кількох підключених каталогах можуть бути index.md або getting-started.md. Якщо натомість потрібно зберегти явні значення name із frontmatter page.json або Markdown, задайте для preserveNames значення true в об’єкті шляху.

Властивості об’єкта шляху:

Властивість Тип Опис
path string Локальний каталог для пошуку. Відносні шляхи визначаються відносно кореня колекції.
prefix string Необов’язковий префікс логічного шляху в межах колекції.
preserveNames boolean Зберігати явні назви сторінок замість генерування назв із шляху з префіксом. Типово — false, якщо задано prefix.
meta object Метадані, об’єднані з кожною сторінкою, знайденою за цим шляхом. У разі повторення ключів перевагу мають метадані сторінки.
render string|object Визначення рендерингу для сторінок Markdown цього шляху, яке перевизначає render завантажувача.

Рендеринг Markdown через компонент

За допомогою render сторінки Markdown, знайдені завантажувачем, рендеряться через renderer сторінок, а не зберігаються як блоки:

PHP
<?php

return array(
  'paths'  => array( __DIR__ . '/external-docs' ),
  'render' => array(
    'entry' => __DIR__ . '/document.tsx',
    'data'  => __DIR__ . '/document.php',
  ),
);

Вони залишаються сторінками Markdown: тип вмісту, шлях до вмісту, відповіді .md і frontmatter не змінюються. Під час синхронізації зберігається один блок blockstudio/page, внутрішній HTML якого — перетворений Markdown, очищений, якщо колекція очищає свій вміст, а не розібрані блоки, тож post_content зберігає текст документа. Renderer отримує цей HTML як слот і може прочитати джерело з page.content_path. Відносні шляхи визначаються відносно кореня колекції; зовнішній фільтр шляхів застосовується так само, як і до шляхів. Сторінка, у frontmatter якої задано власний render або render: false, не включається.

Макети

Файл layout.php обгортає відображення сторінки на основі файла у фронтенді. Він не замінює синхронізований post_content, збережений у WordPress, і не обгортає полотно редактора. Макет виконується лише для запитів до окремих сторінок у фронтенді.

Для колекцій розмістіть layout.php поруч із pages.json, щоб обгорнути ним кожну сторінку цієї колекції у фронтенді:

PHP
<?php $current = blockstudio_current_page(); ?>

<main class="docs-layout">
  <aside>
    <?php foreach (blockstudio_page_tree('docs') as $item) : ?>
      <?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
      <a
        href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
        <?php echo $is_current ? 'aria-current="page"' : ''; ?>
      >
        <?php echo esc_html($item['title']); ?>
      </a>
    <?php endforeach; ?>
  </aside>

  <article>
    <?php echo blockstudio_page_content(); ?>
  </article>
</main>

blockstudio_page_content() виводить тіло сторінки, яке WordPress зазвичай відображає через the_content. Якщо макет не виводить blockstudio_page_content(), вміст сторінки навмисно приховано.

У макетах можна використовувати допоміжні функції сторінки:

PHP
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();

Вкладені сторінки, що не належать до колекцій, також можуть успадковувати найближчий батьківський layout.php у дереві pages. Для сторінок колекцій кореневий макет колекції зберігається в кожному синхронізованому записі та враховується у відбитку сторінки, тому зміни макета застосовуються під час наступної синхронізації.

Макети renderer

Макетом також може бути запис renderer, наприклад layout.tsx для renderer, який реєструє layouts: ["layout.tsx"]. Його шукають у тих самих місцях, що й layout.php, а необов’язковий layout.data.php поруч із ним є завантажувачем даних. Під час рендерингу renderer отримує kind: "layout" і відрендерений вміст сторінки як slot із тим самим пріоритетом the_content, що й layout.php. У каталозі може бути або layout.php, або один макет renderer, але не обидва; наявність обох спричиняє помилку пошуку. Помилка макета викликає blockstudio/pages/layout_error, а вміст сторінки залишається без обгортки, як і у випадку з layout.php.

Режим редагування блоків

Властивість blockEditingMode визначає, як можна редагувати блоки в редакторі. Задайте типове значення для сторінки в page.json, а для окремих елементів перевизначте його в шаблоні:

JSON
{
  "name": "about",
  "title": "About Us",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>
Значення Опис
"default" Повне редагування. Блоки можна вибирати, переміщувати й редагувати
"contentOnly" Лише редагування тексту. Текст блоків можна редагувати, але налаштування та структуру заблоковано
"disabled" Без редагування. Блоки повністю неінтерактивні

Перевизначення для окремих елементів задаються атрибутами HTML на будь-якому елементі (<h1>, <p>, <div> тощо) або на елементах <block>. Батьківські блоки-контейнери для перевизначених елементів автоматично отримують значення contentOnly, щоб їхні дочірні елементи залишалися доступними. Це каскадне правило поширюється від перевизначеного елемента вгору до кореня сторінки, тож задавати blockEditingMode потрібно лише для елементів, які мають бути доступними для редагування.

Блокування шаблону

Властивість templateLock визначає, як користувачі можуть редагувати сторінку в редакторі:

Значення Додавання/видалення Переміщення Редагування вмісту
"all" Ні Ні Ні
"insert" Ні Так Так
"contentOnly" Ні Ні Так
false Так Так Так

Якщо задано templateLock, Blockstudio вимикає можливість розблокувати блоки через UI редактора.

Віртуальні маршрути

Деякі документи не мають відповідних записів: довідник компонентів, згенерований із даних, каталог або розділ облікового запису. Зареєструйте їх як віртуальні маршрути замість того, щоб самостійно підключати template_redirect:

PHP
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

Шлях задається відносно головної сторінки сайту. За наявності prefix маршрут також обслуговує всі вкладені шляхи, а match отримує решту шляху (порожній рядок для самого маршруту) та повертає значення, яке отримає функція зворотного виклику рендерингу, або null, щоб передати URL до WordPress, який відповість 404 як зазвичай. Функція зворотного виклику рендерингу виводить документ або повертає його як рядок; title — це рядок або замикання, що отримує значення збігу.

Для запиту, що відповідає маршруту, Blockstudio не дозволяє WordPress позначити його як 404, а redirect_canonical — перенаправити його; скидає стан окремої сторінки, про який повідомляє основний запит; надсилає статус (типово status, 200) і виконує рендеринг із пріоритетом Virtual_Routes::PRIORITY у template_redirect. Це відбувається відразу після того, як буфер виводу Blockstudio відкривається в Assets::BUFFER_PRIORITY, тому завершений документ отримує свої ресурси блоків, об’єднані ресурси UI і скомпільований Tailwind, як і будь-яка сторінка, та до redirect_canonical із пріоритетом 10. Обробник, який самостійно рендерить цілий документ, має також запускатися після Assets::BUFFER_PRIORITY, інакше цей етап обробки буде пропущено. Шляхи з urls (типово сам шлях маршруту, якщо він не є префіксним) додаються до збірок попереднього рендерингу, а Virtual_Routes::urls() повертає їх як абсолютні URL для карти сайту. Virtual_Routes::match( $path ) визначає шлях так само, як це зробив би запит.

Поведінка синхронізації

Записи сторінок змінюються лише під час явної операції синхронізації:

Командна оболонка
wp bs pages sync

Команда знаходить повний перелік джерел, створює або оновлює змінені записи, видаляє підтверджені записи-сироти, оновлює маршрутизацію колекцій і конфігурацію скомпільованого templateFor та повідомляє про зміни. Додайте --authoritative, щоб замінити керований вміст замість збереження вмісту редактора з ключами, а --full — щоб позначити цей прохід як повне узгодження незалежно від збереженої ідентичності джерела:

Командна оболонка
wp bs pages sync --authoritative --full

Звичайні запити до фронтенду, адмінпанелі, AJAX, REST, cron і загального завантаження WP-CLI не виконують повний пошук сторінок, не запитують керований інвентар для узгодження та не записують сторінки. Вони використовують уже синхронізовані записи WordPress, а також компактну конфігурацію колекцій і шаблонів типів записів, збережену під час останньої явної операції. Під час першого запуску або оновлення система може один раз просканувати маніфести колекцій, щоб відновити метадані маршрутизації; це доступне лише для читання завантаження не синхронізує вміст. Автентифікований, необов’язковий кінцевий маршрут оновлення Canvas є явною операцією API для створення вмісту: Canvas викликає його один раз під час відкриття робочого простору, щоб нові або змінені джерела з’явилися в початковому переліку. Live-режим викликає цей самий механізм, коли виявляє зміну джерела сторінки.

Blockstudio\Pages::init() тепер реєструє лише хуки під час обробки запиту. Інтеграції, які раніше передавали аргумент force цьому методу, мають натомість викликати Blockstudio\Pages::reconcile() або виконувати wp bs pages sync.

Щоб запобігти перезапису сторінки після ручного редагування, задайте "sync": false у page.json.

Переносні розташування джерел

Синхронізовані файли тем зберігаються як шляхи відносно теми, а не як абсолютні шляхи встановлення. Файли дочірньої та батьківської тем мають окремі ідентичності, навіть якщо їхні відносні імена файлів збігаються. Допоміжні функції сторінок і далі повертають розв’язані абсолютні значення template_path, content_path, layout_path та directory для поточного запиту.

Це дає змогу CLI синхронізації та вебзапитам використовувати різні корені файлової системи, як-от на хостингу з обмеженим доступом, не порушуючи відповіді Markdown, макети, сканування Tailwind або відстеження вихідних файлів попереднього рендерингу. Наявні абсолютні шляхи теми перебазовуються під час читання, якщо назва каталогу теми не змінилася. Щоб читати їх, не потрібні синхронізація, міграція бази даних чи запис метаданих під час запиту; наступна явна синхронізація збереже переносні шляхи.

Якщо каталог теми є символічним посиланням, наприклад на каталог розробки, зберігаються ті самі розташування theme: незалежно від того, чи джерело прочитано через символічне посилання, чи через його ціль, а шляхи вказують на налаштований каталог теми.

Файли поза активними дочірньою та батьківською темами й надалі підтримуються за налаштованими абсолютними шляхами з урахуванням обмежень PHP open_basedir. Їх не можна автоматично перемістити: після переміщення зовнішнього джерела оновіть його налаштований шлях і запустіть явну синхронізацію.

Власність полів запису

postStatus задає початковий статус. Наступні синхронізації зберігають наявні статуси чернетки, очікування, приватної публікації, опублікованого та запланованого запису, зокрема з --authoritative. Чернетка не буде опублікована повторно лише через те, що у її файлі зазначено postStatus: "publish". Наявна поведінка відновлення осиротілих записів не змінюється: явна синхронізація відновлює видалений до кошика керований запис, якщо його джерело наявне. Заблокуйте сторінку або вимкніть синхронізацію, щоб запобігти такому відновленню.

Файл і надалі визначає заголовок, ярлик, тип запису, батьківський запис і налаштований порядок у меню. Редагування цих значень у WordPress не змінює визначення джерела. Під час наступної явної синхронізації повторно застосовуються значення з файлу, а назви відповідних полів зазначаються в pages.<name>.overwritten, із попередженням у виводі таблиці CLI. Власні дозволи WordPress також діють, зокрема порожній ярлик для записів зі статусом очікування, якщо користувач, який виконує синхронізацію, не може їх опублікувати.

Використовуйте blockstudio/pages/update_post_data для інтеграції, яка явно керує іншою політикою статусів. Блоки з ключами зберігають вміст, яким керує редактор; ключі не змінюють власника заголовка чи ярлика запису.

Для сторінок колекцій відбитки охоплюють маніфест, завантажувач, джерело сторінки, файл макета, метадані та пов’язані шляхи до джерел. Під час наступної явної синхронізації зміни в цих входах буде застосовано.

Коли джерело колекції видаляється, Blockstudio видаляє згенеровану сторінку, щоб старі сторінки колекції не залишалися після зникнення файла джерела. Типово сторінки колекції-сироти переміщуються до кошика. Використовуйте blockstudio/pages/orphan_action, щоб повернути trash, delete або keep.

Під час запитів до фронтенду Blockstudio завантажує реєстр сторінок із уже синхронізованих опублікованих записів. Чернетки та приватні сторінки доступні в контекстах адмінпанелі й синхронізації, але допоміжні функції фронтенду завантажують лише опубліковані сторінки.

Узгодження розгортання

Blockstudio\Pages::reconcile() — це точка входу для розгортання PHP. Вона знаходить повний бажаний інвентар, порівнює відбитки джерел і рушія синхронізації та повертає машинозчитуваний звіт:

PHP
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
  'renames' => [
    [
      'from' => 'pages/old/index.php',
      'to' => 'pages/new/index.php',
    ],
  ],
]);

Звіт містить discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, результати для кожної сторінки, помилки виявлення та детермінований sourceIdentity.

Заблоковані сторінки мають status: "locked" і рахуються окремо від сторінок без змін. У removedPages для кожної видаленої сторінки наведено name, key, postId та фактичний action (trash або delete); збережені або вже переміщені до кошика записи не рахуються як щойно видалені. У виводі таблиці CLI також зазначаються створені, оновлені, заблоковані, видалені та збережені за вмістом сторінки разом з ID записів.

Після аналізу та об’єднання за ключами, якщо кінцевий запис ідентичний попередньому, wp_update_post() не викликається, post_modified не змінюється, нова ревізія не створюється та хуки оновлення запису не запускаються. Результат має статус unchanged. Якщо вміст джерела відрізняється від вмісту, яким керує редактор у блоках із ключами, preserved: true позначає це рішення, а загальний лічильник preserved враховує такий випадок. Новий відбиток джерела та керовані метадані все одно зберігаються, тож під час наступної синхронізації без змін нічого не відбувається. preserved — це додатковий прапорець, а не окремий статус: сторінка може зберегти вміст блоків із ключами й водночас оновити заголовок, заданий у файлі, або додати інший блок.

authoritative: true може зняти блокування Page Sync і замінює вміст визначенням із файла замість збереження вмісту редактора з ключами. Для звичайної явної синхронізації залиште його false. plan_valid: false, full: true, broad: true, відсутність попередньої ідентичності джерела або змінений відбиток рушія синхронізації позначають прохід як повне узгодження (fullReconciliation у звіті). У будь-якому разі кожен прохід порівнює повний інвентар. Записи перейменування Git — лише підказки щодо ідентичності. Вони ніколи не замінюють порівняння повного інвентарю.

Однакові відбитки за незмінних шляхів виконання не спричиняють записів у запис або postmeta та не запускають хуки оновлення. Коли незмінене джерело переміщується до нового каталогу випуску, узгодження оновлює лише збережені шляхи до шаблону, вмісту, макета й каталогу; воно не оновлює post_content або часову позначку зміни запису. Керовані сторінки, яких бракує, видаляються лише після завершення повного узгодження без помилок пошуку чи запису сторінок.

Пряме узгодження API не позначає розгортання як успішне. Після активації та перевірки відповідного статичного артефакту й маршрутів явно збережіть повернуту ідентичність:

PHP
Blockstudio\Pages::store_successful_source_identity(
  $report['sourceIdentity']
);

wp bs pages sync зберігає повернуту ідентичність після успішного проходу. Звичайне завантаження WP-CLI лише реєструє збережені типи записів колекцій і правила перезапису URL. Воно не шукає сторінки й не синхронізує їх.

Фіксація ID запису

Типово WordPress автоматично призначає ID записам. Якщо сторінку видалити й створити знову, ID зміниться, порушивши зовнішні посилання, наприклад меню або жорстко прописані посилання.

Використовуйте postId, щоб закріпити за сторінкою певний ID:

JSON
{
  "name": "about",
  "title": "About Us",
  "postId": 42
}

Під час створення сторінки Blockstudio передає ID до WordPress через import_id. Якщо ID вільний, WordPress використовує його без змін. Якщо цей ID уже належить іншому запису, WordPress непомітно призначає новий ID автоматично.

Під час пошуку наявних сторінок Blockstudio спочатку перевіряє закріплений ID, а потім метадані або слаґ. Тож якщо сторінку видалити й синхронізувати знову, вона отримає той самий ID.

Об’єднання блоків за ключами

Типово, коли файл шаблону змінюється, Blockstudio замінює весь вміст запису новим шаблоном. Це означає, що всі зміни в редакторі WordPress буде втрачено.

Додайте блокам атрибут key, щоб зберігати зміни користувача під час синхронізації шаблонів. Якщо шаблон містить блоки з ключами, Blockstudio об’єднує зміни шаблону з наявним вмістом запису, а не замінює його.

Додавання ключів

Використовуйте атрибут key для будь-якого елемента HTML або <block>:

HTML
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>

<div key="features">
  <p>First feature.</p>
  <p>Second feature.</p>
</div>

<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h2>Hero Title</h2>
  <p>Hero description.</p>
</block>

<block
  name="acme/testimonial"
  key="featured-quote"
  quote="Default quote"
/>

Ключі мають бути унікальними в усьому шаблоні. Ключ захищає весь блок і весь його вміст. Не потрібно задавати ключі окремим дочірнім елементам усередині батьківського блока з ключем. Блоки з ключами можна переміщувати в будь-яке місце або на будь-який рівень вкладеності між оновленнями шаблону — їхній вміст, доданий користувачем, збережеться.

Так само працюють ключі для власних блоків Blockstudio. key — це структурні метадані Page Sync; значення власних полів залишаються звичайними атрибутами Blockstudio. Коли редактор змінює ці поля, наступна синхронізація шаблону зберігає значення редактора й водночас застосовує незалежні зміни шаблону. Сторінки, створені в старіших версіях із ключем усередині даних власного поля, автоматично переносяться під час наступної синхронізації.

Як працює об’єднання

Коли файл шаблону змінюється й сторінку синхронізовано повторно:

Блок Поведінка
Блок із ключем Вміст користувача й значення полів Blockstudio зберігаються. Застосовуються атрибути та структура, задані шаблоном.
Блок без ключа Повністю замінюється версією із шаблону (так само, як без ключів)

Приклади

Зміни користувача в блоках із ключами зберігаються:

  1. Шаблон задає <p key="intro">Default intro.</p>
  2. Користувач змінює абзац у редакторі на "Власний вступний текст."
  3. Розробник оновлює шаблон, додає новий блок і змінює макет
  4. Під час синхронізації абзац залишається "Власний вступний текст.", а новий макет застосовується

Атрибути шаблону все одно застосовуються:

  1. У шаблоні є блок обкладинки з key="hero" та атрибутом url
  2. Розробник змінює атрибут url обкладинки на нове фонове зображення
  3. Під час синхронізації застосовується нове фонове зображення, але зміни вмісту користувача всередині обкладинки зберігаються

Особливі випадки

Сценарій Поведінка
До шаблону додано новий блок із ключем З’являється з типовим вмістом шаблону
Блок із ключем видалено із шаблону Видаляється із запису
Тип блока змінено (ключ той самий) Шаблон повністю перемагає, об’єднання вмісту не відбувається
Дублікати ключів Друге входження вважається блоком без ключа
У шаблоні немає ключів Повна заміна (як і без ключів)
Примусова синхронізація Повна заміна, ключі ігноруються
Заблокований запис Синхронізація не виконується

Поєднання з елементами керування редагуванням

Ключі, templateLock і blockEditingMode разом дають змогу точно контролювати, що можуть і чого не можуть робити клієнти. Ось типові сценарії роботи.

Повністю заблокована сторінка

Розробник контролює все. Сторінка має статичний макет, до якого клієнти не можуть торкатися. Це зручно для юридичних сторінок, умов надання послуг або будь-якої сторінки, яку слід змінювати лише через код.

JSON
{
  "name": "terms",
  "title": "Terms of Service",
  "templateLock": "all"
}
HTML
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>

Ключі не потрібні. Шаблон є єдиним джерелом правди. Кожна синхронізація повністю перезаписує сторінку.

Заблокований макет із редагованим вмістом

Найпоширеніший сценарій. Заблокуйте структуру сторінки, щоб клієнти не могли додавати, видаляти чи переставляти блоки, але дозвольте їм редагувати текст у певних місцях. Ключі гарантують, що їхні зміни збережуться під час оновлення шаблону.

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Title</h1>
  <p blockEditingMode="contentOnly">Edit this description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">Contact Us</block>
</block>

Клієнт може редагувати заголовок головного блока, опис і вступ до розділу з перевагами. Більше нічого. Текст кнопки, URL і фонове зображення обкладинки контролює розробник. Коли розробник оновлює шаблон (e.g., додає другу кнопку), секції з ключами зберігають текст клієнта.

Шаблон, що розвивається зі збереженням вмісту

Для сторінок, які з часом розростаються. Розробник додає до шаблону нові секції, і кожна синхронізація додає новий вміст, не змінюючи вже налаштованого клієнтом.

HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
  <h2>Our Services</h2>
  <p>We offer great things.</p>
</div>
<div key="testimonials">
  <h2>Testimonials</h2>
  <p>What our clients say.</p>
</div>
<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
</block>

Під час синхронізації з’являються новий розділ відгуків і кнопка. Правки клієнта в заголовку, вступі та переліку послуг не змінюються.

Одноразова заготовка

Створіть сторінку з початковою структурою, а потім повністю передайте її клієнту. Установіть sync на false, щоб звичайна синхронізація ніколи не створювала й не оновлювала цю сторінку, і створіть її один раз за допомогою Blockstudio\Pages::force_sync('blog'). Після цього сторінка повністю належить клієнту.

JSON
{
  "name": "blog",
  "title": "Blog",
  "sync": false
}
HTML
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>

wp bs pages sync пропускає цю сторінку, тому force_sync() створює її один раз. Після цього клієнт може вільно додавати, видаляти й переміщувати блоки. Зміни шаблону ігноруються.

Прив’язки блоків

Альтернативою об’єднанню за ключами є використання WordPress core Прив’язок блоків API для зв’язування блоків із метаданими запису. Це не функція Blockstudio, а вбудована можливість WordPress API. Blockstudio просто передає атрибут metadata до згенерованої розмітки блока. Вміст зберігається в метаданих запису, а не в розмітці блока, тому під час синхронізації шаблону розмітку можна вільно перезаписувати: редактор читає дані з метаданих, а не з innerHTML.

Передайте атрибут metadata будь-якому елементу HTML або <block>:

HTML
<h1
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
  Default Title
</h1>

<p
  metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
  Default description text.
</p>

<img
  metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>

Ключі метаданих потрібно зареєструвати з увімкненим show_in_rest:

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest'  => true,
    'single'        => true,
    'type'          => 'string',
    'default'       => 'Default Title',
) );

Ключі та прив’язки

Аспект Ключі Прив’язки
Де зберігається вміст У розмітці блока (post_content) У метаданих запису (wp_postmeta)
Зберігається під час синхронізації шаблону Так (об’єднується за ключем) Так (дані зберігаються в метаданих)
Можна запитувати через WP_Query Ні Так (meta_query)
Доступно в REST API Ні Так
Потрібна реєстрація Ні Так (register_post_meta)
Користувач може переміщувати блоки Ні (шаблон знову встановлює структуру) Ні (шаблон знову встановлює структуру)

В одному шаблоні можна використовувати обидва підходи. Використовуйте ключі для секцій, де важлива структура блоків (e.g., група з кількома дочірніми елементами). Використовуйте прив’язки для окремих полів, дані яких потрібно зробити доступними за межами редактора блоків.

Шаблони типів записів

Використовуйте templateFor, щоб призначити сторінку шаблоном за замовчуванням для типу запису:

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}

Усі нові записи цього типу матимуть визначену структуру блоків.

Власні шляхи

За замовчуванням Blockstudio сканує get_template_directory() . '/pages'. Додайте інші шляхи за допомогою фільтра:

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

Інтеграції середовища виконання, що об’єднують файли з кількох кореневих каталогів, можуть замінити сканування файлової системи на логічне джерело виявлення. Маніфести сторінок, макети, завантажувачі та вихідні шаблони тоді визначаються за логічним шляхом, навіть якщо вибрані файли містяться в різних кореневих каталогах.

Фільтри та дії

Для виявлення сторінок, синхронізації та маршрутизації колекцій доступні такі точки розширення:

Хук Тип Опис
blockstudio/pages/paths Фільтр Додати каталоги, у яких Blockstudio шукає джерела сторінок.
blockstudio/pages/collection_post_type_args Фільтр Налаштувати аргументи register_post_type() для CPT колекції.
blockstudio/pages/template_candidates Фільтр Налаштувати назви файлів шаблонів, які розглядаються як джерела сторінок.
blockstudio/pages/serve_markdown Фільтр Увімкнути або вимкнути необроблені відповіді Markdown.
blockstudio/pages/orphan_action Фільтр Повернути trash, delete або keep для очищення осиротілих записів.
blockstudio/pages/docs_allowed_html Фільтр Налаштувати дозволені HTML для згенерованого вмісту документації Markdown.
blockstudio/pages/allow_external_loader_path Фільтр Дозволити завантажувачу paths працювати поза кореневим каталогом колекції.
blockstudio/pages/manifest_scan_interval Фільтр Задати максимальний вік кешу маніфесту до 7.6.2, який може використати для початкового заповнення збереженої конфігурації середовища виконання під час оновлення.
blockstudio/pages/create_post_data Фільтр Змінити дані запису перед створенням синхронізованої сторінки.
blockstudio/pages/update_post_data Фільтр Змінити дані запису перед оновленням синхронізованої сторінки.
blockstudio/pages/sync_engine_inputs Фільтр Додати версію аналізатора, зіставлення або міграції, яка має навмисно розширити узгодження один раз.
blockstudio/pages/post_created Дія Виконується після створення запису синхронізованої сторінки.
blockstudio/pages/post_updated Дія Виконується після оновлення запису синхронізованої сторінки.
blockstudio/pages/synced Дія Виконується після завершення синхронізації реєстру сторінок.
blockstudio/pages/reconciled Дія Виконується після явного узгодження разом із машиночитаним звітом.
blockstudio/pages/renderers Дія Реєструє засоби рендерингу сторінок у Blockstudio\Page_Renderers::register(). Виконується один раз за запит.
blockstudio/pages/rendered Дія Виконується після рендерингу сторінки компонента; передає сторінку, її HTML та залежності.
blockstudio/pages/layout_error Дія Виконується, коли макет неможливо відрендерити; передає помилку, шлях до макета та сторінку.

PHP API

PHP
// Get all registered pages.
$pages = Blockstudio\Pages::pages();

// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');

// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');

// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');

// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');

// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');

// Get a specific page.
$page = Blockstudio\Pages::get_page('about');

// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');

// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');

// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();

// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
  'authoritative' => true,
  'plan_valid' => true,
  'source' => [
    'commit' => $commit,
    'dirtyHash' => $dirtyHash,
  ],
]);

// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);

// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');

// Unlock a page.
Blockstudio\Pages::unlock('about');

// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
  'extensions' => ['tsx'],
  'layouts' => ['layout.tsx'],
  'render' => 'my_theme_render_page',
]);

// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');

// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);

Докладніше про семантику аргументів, поля звіту та межі перевірки ідентичності джерела див. у розділі Узгодження розгортання.

Для шаблонів і макетів доступні глобальні допоміжні функції:

PHP
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();

Масиви сторінок, які повертають Blockstudio\Pages::pages(), Blockstudio\Pages::tree(), Blockstudio\Pages::children() і глобальні допоміжні функції, містять ідентифікатор синхронізованого запису, шляхи до джерела й шаблону, метадані колекції та шляху, тип вмісту, політику синхронізації, тип і статус запису, політику редагування, власні метадані та ключ permalink. Метадані колекції завантажуються з останнього успішного явного узгодження. Під час звичайних запитів ці дані середовища виконання відновлюються зі збереженої конфігурації та метаданих синхронізованих записів без читання дерев вихідних файлів сторінок. Клас Pages не надає окремого методу для постійного посилання.

Створення сторінок на основі файлів

Блокування шаблонів, режими редагування блоків, об’єднання за ключами та керування тим, що можуть редагувати клієнти.