Сторінки
Сторінки — це шаблони на основі файлів, які синхронізуються з базою даних WordPress як записи. Синхронізація виконується явно: запустіть wp bs pages sync або викличте сторінки API, коли потрібно застосувати зміни джерела. Завантаження інтерфейсу сайту або адмінпанелі WordPress ніколи не виконує повне виявлення сторінок і не змінює записи сторінок.
Сторінки можна визначати як одну папку page.json, як окремі Markdown або як колекцію з маніфестом pages.json. Колекції корисні для документації, баз знань, бібліотек цільових сторінок або будь-яких наборів вкладених сторінок, які потрібно генерувати з файлів.
page.json
Щоб визначити сторінку через JSON, додайте файл конфігурації page.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 замість посилання на сусідній файл:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"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:
<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:
<!-- 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 не потрібен, бо цей ідентифікатор визначають маніфест колекції та шлях до файлу.
---
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.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
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:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
Запит .md URL, який не відповідає сторінці на основі Markdown, повертає 404, лише якщо шлях належить до колекції сторінок. Поза всіма колекціями Blockstudio не перехоплює запит, залишаючи його для обробки WordPress та іншими плагінами.
Сторінки компонентів
Сторінка компонента відображається засобом рендерингу сторінок, а не зберігається як блоки. Blockstudio не постачається із засобом рендерингу. Тема або плагін реєструє такий засіб для оброблюваних ним файлів запису, наприклад засіб рендерингу React для page.tsx, а Blockstudio викликає його, передаючи сторінку, запис WordPress і вміст відрендереного слота.
pages/legal-notice/
page.json
page.tsx
data.php
{
"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.*, його розбирають як будь-яке джерело сторінки, і його вміст стає внутрішніми блоками блока — його слотом:
<!-- 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 і запити до фронтенду бачать той самий реєстр.
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, файли, прочитані під час рендерингу, і необов’язкові ресурси:
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
{
"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' ).
{
"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
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. Якщо ці шляхи розташовані поза коренем колекції, до них застосовується той самий фільтр зовнішніх шляхів.
Використовуйте рядковий елемент, якщо зовнішній каталог має зберігати власні логічні шляхи. Використовуйте об’єктний елемент, щоб підключити каталог із префіксом шляху колекції:
'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
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 $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(), вміст сторінки навмисно приховано.
У макетах можна використовувати допоміжні функції сторінки:
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, а для окремих елементів перевизначте його в шаблоні:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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:
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. Вона знаходить повний бажаний інвентар, порівнює відбитки джерел і рушія синхронізації та повертає машинозчитуваний звіт:
$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 не позначає розгортання як успішне. Після активації та перевірки відповідного статичного артефакту й маршрутів явно збережіть повернуту ідентичність:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
wp bs pages sync зберігає повернуту ідентичність після успішного проходу. Звичайне завантаження WP-CLI лише реєструє збережені типи записів колекцій і правила перезапису URL. Воно не шукає сторінки й не синхронізує їх.
Фіксація ID запису
Типово WordPress автоматично призначає ID записам. Якщо сторінку видалити й створити знову, ID зміниться, порушивши зовнішні посилання, наприклад меню або жорстко прописані посилання.
Використовуйте postId, щоб закріпити за сторінкою певний ID:
{
"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>:
<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 зберігаються. Застосовуються атрибути та структура, задані шаблоном. |
| Блок без ключа | Повністю замінюється версією із шаблону (так само, як без ключів) |
Приклади
Зміни користувача в блоках із ключами зберігаються:
- Шаблон задає
<p key="intro">Default intro.</p> - Користувач змінює абзац у редакторі на "Власний вступний текст."
- Розробник оновлює шаблон, додає новий блок і змінює макет
- Під час синхронізації абзац залишається "Власний вступний текст.", а новий макет застосовується
Атрибути шаблону все одно застосовуються:
- У шаблоні є блок обкладинки з
key="hero"та атрибутомurl - Розробник змінює атрибут
urlобкладинки на нове фонове зображення - Під час синхронізації застосовується нове фонове зображення, але зміни вмісту користувача всередині обкладинки зберігаються
Особливі випадки
| Сценарій | Поведінка |
|---|---|
| До шаблону додано новий блок із ключем | З’являється з типовим вмістом шаблону |
| Блок із ключем видалено із шаблону | Видаляється із запису |
| Тип блока змінено (ключ той самий) | Шаблон повністю перемагає, об’єднання вмісту не відбувається |
| Дублікати ключів | Друге входження вважається блоком без ключа |
| У шаблоні немає ключів | Повна заміна (як і без ключів) |
| Примусова синхронізація | Повна заміна, ключі ігноруються |
| Заблокований запис | Синхронізація не виконується |
Поєднання з елементами керування редагуванням
Ключі, templateLock і blockEditingMode разом дають змогу точно контролювати, що можуть і чого не можуть робити клієнти. Ось типові сценарії роботи.
Повністю заблокована сторінка
Розробник контролює все. Сторінка має статичний макет, до якого клієнти не можуть торкатися. Це зручно для юридичних сторінок, умов надання послуг або будь-якої сторінки, яку слід змінювати лише через код.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
Ключі не потрібні. Шаблон є єдиним джерелом правди. Кожна синхронізація повністю перезаписує сторінку.
Заблокований макет із редагованим вмістом
Найпоширеніший сценарій. Заблокуйте структуру сторінки, щоб клієнти не могли додавати, видаляти чи переставляти блоки, але дозвольте їм редагувати текст у певних місцях. Ключі гарантують, що їхні зміни збережуться під час оновлення шаблону.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<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., додає другу кнопку), секції з ключами зберігають текст клієнта.
Шаблон, що розвивається зі збереженням вмісту
Для сторінок, які з часом розростаються. Розробник додає до шаблону нові секції, і кожна синхронізація додає новий вміст, не змінюючи вже налаштованого клієнтом.
<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>
<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'). Після цього сторінка повністю належить клієнту.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<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>:
<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:
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, щоб призначити сторінку шаблоном за замовчуванням для типу запису:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
Усі нові записи цього типу матимуть визначену структуру блоків.
Власні шляхи
За замовчуванням Blockstudio сканує get_template_directory() . '/pages'. Додайте інші шляхи за допомогою фільтра:
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
// 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]);
Докладніше про семантику аргументів, поля звіту та межі перевірки ідентичності джерела див. у розділі Узгодження розгортання.
Для шаблонів і макетів доступні глобальні допоміжні функції:
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 не надає окремого методу для постійного посилання.
Створення сторінок на основі файлів
Блокування шаблонів, режими редагування блоків, об’єднання за ключами та керування тим, що можуть редагувати клієнти.