Страницы
Страницы — это шаблоны на основе файлов, которые синхронизируются с базой данных 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; он не преобразуется в дополнительные блоки. Не смешивайте теги блоков HTML Blockstudio с этим форматом, ожидая, что они будут преобразованы. Обычные комментарии 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 с расширением 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 сохраняет ту же структуру URL для исходного Markdown:
| Страница 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 определяется типом запроса, а не посетителем, поэтому чтение этого значения рендерером не нарушает побайтовое совпадение для вошедших в систему и анонимных пользователей. Если рендерер завершится с ошибкой, он выбросит исключение: страница не отобразится с пустым содержимым. В режиме предпросмотра редактора REST блок вместо этого показывает ошибку в виде уведомления. После успешного рендеринга действие blockstudio/pages/rendered получает страницу, HTML и её зависимости.
assets перечисляет файлы скриптов и стилей, необходимые странице. К ним применяются те же процедуры обработки ресурсов блоков (соглашение *.inline.*, ES-модули, минификация и ?ver), а страница выводит их один раз через тот же буфер, что и ресурсы блоков, поэтому предварительно отрендеренная страница содержит их. Ресурс может задать version, чтобы заменить своё значение ?ver. Код вне рендерера может использовать тот же канал через 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 остаются 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. |
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. Задайте для preserveNames значение true в объекте пути, если нужно сохранить явные значения name из frontmatter page.json или Markdown.
Свойства объекта пути:
| Свойство | Тип | Описание |
|---|---|---|
path |
string |
Локальный каталог для поиска. Относительные пути разрешаются от корня коллекции. |
prefix |
string |
Необязательный префикс логического пути внутри коллекции. |
preserveNames |
boolean |
Сохранять явные имена страниц вместо генерации имён по префиксному пути. Если задано prefix, по умолчанию используется false. |
meta |
object |
Метаданные, объединяемые с каждой страницей, найденной по этому пути. При совпадении ключей приоритет имеют метаданные страницы. |
render |
string|object |
Описание рендеринга для страниц Markdown по этому пути, переопределяющее render загрузчика. |
Рендеринг Markdown с помощью компонента
При использовании render обнаруженные загрузчиком страницы Markdown рендерятся с помощью рендерера страниц, а не сохраняются в виде блоков:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
Они остаются страницами Markdown: тип содержимого, путь к содержимому, ответы .md и фронтматтер не меняются. Синхронизация сохраняет один блок blockstudio/page, у которого внутренний HTML — это преобразованный Markdown, очищенный, если коллекция очищает своё содержимое, вместо разобранных блоков, поэтому post_content сохраняет текст документа. Рендерер получает этот HTML в качестве слота и может прочитать источник из page.content_path. Относительные пути разрешаются от корня коллекции; к ним применяется внешний фильтр путей. Страница исключается, если в её фронтматтере задано собственное 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. Для страниц коллекции корневой макет коллекции сохраняется в каждой синхронизированной записи и учитывается в отпечатке страницы, поэтому изменения макета применяются при следующей синхронизации.
Макеты рендерера
Макет также может быть записью рендерера, например layout.tsx для рендерера, регистрирующего layouts: ["layout.tsx"]. Он ищется в тех же местах, что и layout.php; расположенный рядом необязательный layout.data.php служит загрузчиком данных. При рендеринге рендерер получает kind: "layout" и отрендеренное содержимое страницы как slot с тем же приоритетом the_content, что и у layout.php. В каталоге может находиться layout.php или один макет рендерера, но не оба варианта одновременно; наличие обоих считается ошибкой поиска. При сбое макета срабатывает 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 вызывает его один раз при открытии рабочей области, чтобы новые или изменённые источники появились в исходном перечне. В режиме реального времени та же операция вызывается при обнаружении изменения источника страницы.
Теперь 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 может снять блокировку синхронизации страницы и заменяет содержимое данными из описания файла, а не сохраняет содержимое редактора с ключами. Для обычной явной синхронизации оставьте его false. plan_valid: false, full: true, broad: true, отсутствие предыдущего идентификатора источника или изменение отпечатка движка синхронизации помечает проход как полную сверку (fullReconciliation в отчёте). В любом случае каждый проход сравнивает полный перечень ресурсов. Записи переименования Git служат только подсказками для сопоставления идентификаторов. Они не заменяют сравнение полного перечня.
При совпадающих отпечатках и неизменившихся путях выполнения не записываются ни записи, ни метаданные записей и не вызываются хуки обновления. Если неизменённый источник перемещается в новый каталог выпуска, сверка обновляет только сохранённые пути к шаблону, содержимому, макету и каталогу; она не обновляет 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 — это структурные метаданные синхронизации страниц; значения пользовательских полей остаются обычными атрибутами 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 не предоставляет отдельный метод постоянной ссылки.
Создание страниц на основе файлов
Блокировка шаблонов, режимы редактирования блоков, объединение по ключам и управление доступом клиентов к редактированию.