Към съдържанието

Страници

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

Страниците могат да бъдат дефинирани като една папка page.json, като самостоятелни Markdown или като колекция с манифест pages.json. Колекциите са полезни за документация, бази от знания, библиотеки с целеви страници или всякакъв набор от вложени страници, които трябва да се генерират от файлове.

page.json

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

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

Свойства

Свойство Тип По подразбиране Описание
name string задължително Уникален идентификатор на страницата
title string Автоматично от името Заглавието на страницата
slug string Същото като името URL идентификатор в URL адреса за страницата
path string "." Логически път в колекцията
order integer 0 Ред в менюто за синхронизирания запис
postType string "page" WordPress тип на записа
postStatus string "draft" Статус за новите записи (publish, draft, pending, private)
postId integer – Закачане на страницата към конкретен идентификатор на запис 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 и записите на loader, разпознатите ключове включват blockEditingMode, collection, content, contentType, defaults, file, html, markdown, meta, name, order, path, postId, postStatus, postType, postTypeArgs, render, slug, template, templateFor, templateLock и title. Всеки ключ, който не е посочен по-горе, се съхранява в масива meta на страницата.

Източници на съдържание

Дефиницията на страницата определя коя публикация WordPress трябва да съществува. Източникът на съдържание определя какъв markup на блокове се записва в тази публикация.

Когато папка на страница съдържа page.json, Blockstudio търси съседен файл с източник в следния ред:

Файл Употреба
index.php Markup на блокове в стил HTML, чете се както е (кодът на PHP не се изпълнява)
index.blade.php Съдържание на шаблон Blade
index.twig Съдържание на шаблон Twig
index.md Съдържание Markdown

page.json може да предоставя и вградено markdown или html вместо съседен файл:

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

Колекциите добавят още два режима на източник:

  • Файлове Markdown, открити директно в дървото на колекцията.
  • Записи от loader, върнати от loader.php.

Записите от loader могат да използват markdown, html или content с contentType. Могат да сочат и към локален file или template. Типът на файловите източници и шаблоните се определя по разширението, освен ако contentType не е зададен изрично.

Поддържаните стойности на contentType са php, blade, twig, markdown и html. Markdown първо се преобразува в HTML, след което се анализира в естествени блокове на WordPress. Източниците PHP, Blade, Twig и HTML преминават през обичайния парсер на страници Blockstudio.

Класове в основните блокове

Клас class на елемент HTML, съпоставен с основен блок, става негов className. Изричен етикет на основен блок може директно да използва className. И двата варианта запазват класовете в записаната обвивка на блока заедно с класовете, които генерира WordPress:

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

Ако присъстват и двете свойства, предимство има className. Това преобразуване важи само за основните блокове: съпоставянето на персонализиран блок запазва неговото поле class непроменено. Класовете за стил на бутона, например is-style-outline, принадлежат на обвивката на бутона, а не на връзката му.

Изпълнете wp bs pages sync, за да приложите корекциите на парсера към страници, които са синхронизирани по-рано. Надстройките на парсера се разпознават при следващата изрична синхронизация, дори без редакция на изходния файл. Заключените страници и страниците с sync: false запазват обичайните си защити; заявките към фронтенда никога не извършват тази синхронизация.

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

Източниците на страници и шаблони могат да съдържат и сериализирани блокове, копирани от редактора на код WordPress:

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

Когато източникът съдържа разделител за блокове <!-- wp:... -->, Blockstudio използва вградения анализатор на блокове на WordPress за целия източник. Атрибутите, вложените блокове, динамичните блокове като Query Loop и блоковете Blockstudio запазват сериализираната си структура. HTML извън коментарите на блоковете остава в естествения свободен формат HTML; не се преобразува в допълнителни блокове. Не смесвайте етикетите за блокове Blockstudio на HTML с този формат, ако очаквате да бъдат преобразувани. Обикновените коментари HTML не включват режима на сериализирани блокове.

Страници Markdown

Използвайте Markdown, когато текстът трябва да е във файлове, но след синхронизиране да се превърне в редактируемо съдържание на блокове WordPress. Източникът Markdown се преобразува в markup на блокове по време на синхронизирането. Синхронизираната публикация съхранява блокове, а не необработеното тяло на Markdown.

Markdown може да се използва по три начина:

Източник Изисква се frontmatter? Бележки
Самостоятелен pages/example/index.md Да Frontmatter предоставя идентичността на страницата.
page.json плюс index.md Не page.json дефинира страницата, а Markdown предоставя съдържанието.
Markdown в колекция Не Колекцията извежда name и path от местоположението на файла.

Самостоятелен index.md без frontmatter се пропуска, защото Blockstudio няма идентичност на страница за синхронизиране. За Markdown в колекция не е нужен frontmatter, тъй като манифестът на колекцията и пътят до файла предоставят тази идентичност.

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

# About

This Markdown content is synced as native WordPress blocks.

Можете също да съчетаете page.json с index.md. В този случай page.json дефинира страницата, а index.md предоставя съдържанието. Frontmatter в index.md замества съвпадащите стойности в page.json.

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

# Reference

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

За Markdown в колекция пътят до файла става логическият път на страницата, освен ако frontmatter не го замени:

Файл Път по подразбиране
pages/docs/index.md .
pages/docs/getting-started.md getting-started
pages/docs/guide/install/index.md guide/install
pages/docs/guide/install.md guide/install

Непознатите ключове във frontmatter се запазват в масива meta на страницата. Така можете да добавяте данни като section или description и да ги четете от PHP API.

Markdown се анализира като GitHub Flavored Markdown. Разрешен е суров HTML, опасните връзки се премахват, а заглавията без изричен ID получават стабилен такъв. Вложеният frontmatter YAML изисква включения парсер YAML.

Суров Markdown

Източниците на файлове Markdown могат да предоставят оригиналния си изходен код Markdown за външни инструменти и потребители на документацията. Вграденото Markdown няма файл с изходен код, затова се синхронизира с блокове, но не връща суров .md.

Заявете страницата с наставка .md, например https://example.com/docs/reference.md. Или изпратете заглавка Accept: text/markdown към обичайния URL на страницата:

Обвивка
curl -H "Accept: text/markdown" https://example.com/docs/reference/

Frontmatter се премахва от отговора. Успешните отговори със суров Markdown изпращат Content-Type: text/markdown, X-Robots-Tag: noindex и канонична заглавка Link обратно към страницата HTML. Маршрутите .md, които липсват, връщат истински 404.

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

Колекциите Markdown запазват същата структура 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:

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

Заявка .md URL, която не съответства на страница с източник Markdown, връща 404 само когато пътят е в рамките на колекция от страници. Извън всички колекции Blockstudio оставя заявката необработена, за да я обработят WordPress и други приставки.

Страници с компоненти

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

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

render е изрично. Директория с index.php и page.tsx, но без render, остава обикновена страница, така че добавянето на рендерер никога не изобразява повторно съществуваща страница. Формите са:

Стойност Значение
"page.tsx" Само запис, без loader за данни
{ "entry": "page.tsx", "data": "data.php" } Запис и loader за данни
{ "entry": "page.tsx", "renderer": "react" } Запис с изричен идентификатор на рендерер
false Без рендерер, дори когато стойността по подразбиране на колекцията посочва такъв

Пътищата се разрешават спрямо директорията на страницата или спрямо основната директория на колекцията за записите на loader. Те трябва да остават в източника за откриване, освен ако blockstudio/pages/allow_external_loader_path не го позволява. Без renderer се използва рендерерът, който поема разширението на записа. Ако render посочва липсващ запис или файл с данни, неизвестен рендерер или разширение, което никой рендерер не поема, това е грешка при откриването и съгласуването се прекратява, преди да бъде премахнато каквото и да било.

Какво съхранява синхронизирането

Синхронизирането съхранява един блок blockstudio/page. Когато директорията на страницата съдържа и източник index.*, той се анализира като всеки източник на страница и става вътрешните блокове на блока, тоест неговият слот:

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

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

Съхранявайте съдържание, управлявано от WordPress, като шорткодове, в слота. Източник, съставен само от един шорткод, например [download_checkout], се съхранява като блок core/shortcode, така че около резултата му да не се добавя абзац. Той остава в post_content, така че проверките на has_shortcode() го виждат, блоковете на слота с ключове се сливат с редакциите в редактора, както вложените блокове с ключове, а do_shortcode разширява шорткодовете веднъж с обичайния си приоритет the_content, след като рендерерът ги е обградил.

Определението за изобразяване се съхранява със записа като преносими пътища theme:. Отпечатъкът на страницата включва определението, но не и байтовете на записа или loader-а за данни: редактирането на page.tsx или data.php не променя записа, а промените достигат до посетителите чрез изобразяването и графа на статичното предварително изобразяване, който записва записа, loader-а за данни и всеки файл, отчетен от рендерера.

Регистриране на рендерер

Регистрирайте рендерерите чрез действието blockstudio/pages/renderers. То се изпълнява веднъж на заявка, преди първото откриване или изобразяване, така че wp bs pages sync и заявките от предния край виждат един и същ регистър.

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

Идентификаторите на рендерерите са с малки букви. Едно разширение или име на оформление може да принадлежи само на един рендерер, а layout.php остава собственото оформление на Blockstudio. Извикваемият обект получава една заявка:

Ключ Стойност
kind page или layout за оформление с рендерер
renderer Идентификатор на рендерер
entry Абсолютен път до записа
data Абсолютен път до loader-а за данни или null
page Канонични данни на страницата, включително meta
post_id Идентификатор на запис WordPress
slot Изобразено съдържание на слота или съдържанието на страницата за оформление
context frontend, rest, feed или cli

Той връща HTML, файловете, прочетени от рендерирането, и незадължителни ресурси:

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

context идва от типа на заявката, а не от посетителя, така че рендерерът не може да наруши побайтовото съответствие между влезли и анонимни потребители, като го прочете. Ако рендерерът се провали, хвърля грешка: страницата не се визуализира с празно тяло. В редакторски преглед на REST блокът показва грешката като известие. След успешно визуализиране действието blockstudio/pages/rendered получава страницата, HTML и зависимостите ѝ.

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

Редактор

В редактора blockstudio/page показва визуализиран от сървъра преглед на страницата, като слотът е вътрешни блокове, които следват templateLock на страницата. Блокът не може да бъде вмъкнат, дублиран или вложен в друг блок.

Колекции от страници

Колекцията е папка с манифест pages.json. Тя групира множество източници на страници под един slug на колекцията, прилага настройки по подразбиране, поддържа вложени пътища и може автоматично да регистрира отделен тип публикация.

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

Пътищата на страниците в колекцията са логически. Страница с path: "guide/install" се синхронизира като дъщерна на guide, а guide се синхронизира като дъщерна на корена на колекцията, ако тези родителски страници съществуват.

Ако в йерархична колекция има вложена страница, но липсва източникът на междинната родителска страница, Blockstudio генерира празна контейнерна страница за този път, за да запази пълна йерархията WordPress. За не-йерархични типове публикации (без поддръжка на родител page-attributes) празни контейнери не се генерират. Те маршрутизират по съхранения път на колекцията, така че вложени пътища като guide/install и setup/install могат да съществуват едновременно, въпреки че и двата завършват с install.

Типове публикации и URL адреси на колекции

Задайте postType в манифеста на колекцията, за да синхронизирате всички нейни страници с този тип публикация. Не е нужно да повтаряте същата стойност в defaults. Отделните страници все пак могат да заменят postType във frontmatter или page.json.

Когато типът публикация не съществува, Blockstudio го регистрира с show_in_rest: true, редактор като за страници и slug на колекцията като публична основа за URL. postTypeArgs може да замени аргументите за регистрация. Правилата за пренаписване на URL адреси за типовете публикации на колекциите се обновяват автоматично, когато регистрираните типове или аргументите за пренаписване се променят, така че не е нужно да записвате отново постоянните връзки на WordPress.

URL адресите на колекциите използват slug-а на колекцията плюс логическия path на всяка страница:

Път към източника Публичен URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

Този модел URL работи както с йерархични, така и с нейерархични типове публикации за колекции. Blockstudio пренасочва и дублирани URL адреси като /docs/docs/ или /docs/docs/getting-started/ към каноничния URL.

Страниците на колекциите предоставят необработен Markdown на същите URL адреси (вижте Необработен Markdown).

Ако промените колекция от postType: "page" към персонализиран тип публикация, Blockstudio мигрира вече синхронизираните публикации на колекцията на място, когато съхранената им идентичност на страницата съвпада. Така се запазват ID на публикациите, метаданните и съществуващото съдържание, като се избягват дублирани публикации със стария тип. Остарелите публикации на колекцията се почистват във всички статуси според филтъра blockstudio/pages/orphan_action.

Колекции на сайта

Манифест с "scope": "site" групира всички страници под себе си, без да ги превръща в страници на колекция. Използвайте го в корена на дървото със страниците на сайта, за да прилагате споделени стойности по подразбиране и да изброявате страниците на сайта с blockstudio_page_tree( 'my-site' ).

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

Страниците в колекция на сайта запазват същата си идентичност, която имат и без манифеста, така че добавянето му към съществуващо дърво не променя редове за публикации и не създава или изтрива нищо:

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

Зареждащи програми за колекции

Колекциите могат да включват доверен локален loader.php. Използвайте го, когато страниците на колекцията идват от друг локален източник, например външна папка с документация, пакет или генериран манифест.

Зареждащата програма се изпълнява при изрично откриване и синхронизиране на страници. Тя трябва да е детерминистична и локална. Избягвайте да извличате отдалечено съдържание от loader.php, защото това би направило синхронизирането при внедряване зависимо от тази услуга.

PHP
<?php

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

Зареждащата програма може да върне масив с ключове pages, meta и paths:

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

Като съкратен вариант зареждащата програма може да върне директно списък от масиви със страници.

Записите за страници на зареждащата програма могат да предоставят съдържание по следните начини:

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

Файловите препратки на зареждащата програма могат да сочат към източници PHP, Blade, Twig, Markdown или HTML. Относителните пътища се разрешават спрямо корена на колекцията. Абсолютни пътища и пътища извън корена на колекцията са разрешени само ако филтърът blockstudio/pages/allow_external_loader_path ги допуска.

По подразбиране страниците на зареждащата програма са generated: true. Когато генерирана страница изчезне от изхода на зареждащата програма, при следващото синхронизиране Blockstudio третира синхронизираната публикация като осиротяла и я почиства според филтъра blockstudio/pages/orphan_action.

Директориите, посочени в paths, се откриват като обикновените папки на колекцията. Те могат да съдържат файлове Markdown или папки page.json. Ако тези пътища са извън корена на колекцията, се прилага същият филтър за външни пътища.

Използвайте запис с низ, когато външната директория трябва да запази собствените си логически пътища. Използвайте запис с обект, когато директорията трябва да бъде монтирана под префикс на път в колекцията:

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

С тази конфигурация cli-docs/index.md става path: "cli", а cli-docs/getting-started.md става path: "cli/getting-started" в колекцията. Префиксите предотвратяват и конфликти между генерираните имена на страници, така че няколко монтирани директории могат да съдържат съответно index.md или getting-started.md. Задайте preserveNames на true в обекта с пътя, ако вместо това трябва да се запазят изричните стойности name от frontmatter на page.json или Markdown.

Свойства на обекта с пътя:

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

Визуализиране на Markdown чрез компонент

С render страниците Markdown, открити от зареждащ механизъм, се визуализират чрез рендерер на страници, вместо да се съхраняват като блокове:

PHP
<?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 обгръща визуализирането във frontend частта на страница, базирана на файл. Той не заменя синхронизирания post_content, съхранен в WordPress, и не обгръща работната област на редактора. Оформлението се изпълнява само при заявки към единични страници във frontend частта.

За колекции поставете layout.php до pages.json, за да обгърнете всяка страница от тази колекция във frontend частта:

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

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

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

blockstudio_page_content() извежда тялото на страницата, което WordPress обикновено би визуализирал чрез the_content. Ако оформлението не извежда blockstudio_page_content(), съдържанието на страницата умишлено се скрива.

Оформленията могат да използват помощните функции за страници:

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

Вложените страници, които не са част от колекция, също могат да наследят най-близкото оформление layout.php от родителски елемент в дървото pages. При страниците на колекции оформлението на корена на колекцията се съхранява във всяка синхронизирана публикация и се следи като част от отпечатъка на страницата, така че промените в оформлението се прилагат при следващото синхронизиране.

Оформления на рендерера

Оформлението също може да бъде запис за рендерер, например 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 и я замествайте за отделни елементи в шаблона:

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

Заместващите стойности за отделни елементи се задават като атрибути HTML на всеки елемент (<h1>, <p>, <div> и др.) или на елементи <block>. Родителските блокове контейнер на елементите със заместваща стойност автоматично се задават на contentOnly, за да останат достъпни дъщерните им елементи. Това наследяване върви нагоре от елемента със заместваща стойност до корена на страницата, така че трябва да зададете blockEditingMode само на елементите, които искате да направите редактируеми.

Заключване на шаблона

Свойството templateLock определя как потребителите могат да редактират страницата в редактора:

Стойност Добавяне/премахване Преместване Редактиране на съдържание
"all" Не Не Не
"insert" Не Да Да
"contentOnly" Не Не Да
false Да Да Да

Когато е зададен templateLock, Blockstudio деактивира възможността за отключване на блокове чрез UI в редактора.

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

Някои документи нямат свързана публикация: генерирана от данни справка за компонент, каталог или област за потребителски акаунт. Регистрирайте ги като виртуални маршрути, вместо сами да закачате template_redirect:

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

Пътят е относителен спрямо началната страница на сайта. С prefix маршрутът обслужва и всички пътища под него, а match получава остатъка (празен низ за самия маршрут) и връща стойността, която получава функцията за обратно извикване при визуализиране, или null, за да остави URL на WordPress, който отговаря с 404 както обикновено. Функцията за обратно извикване при визуализиране извежда документа или го връща като низ; title е низ или затваряне, което получава стойността на съвпадението.

За съвпадаща заявка Blockstudio не позволява на WordPress да маркира 404, нито на redirect_canonical да я пренасочи, изчиства състоянието за единична страница, отчетено от основната заявка, задава статус (status, 200 по подразбиране) и визуализира с приоритет Virtual_Routes::PRIORITY на template_redirect. Това е непосредствено след като буферът за изход на Blockstudio се отвори при Assets::BUFFER_PRIORITY, така че завършеният документ получава своите блокови ресурси, пакетните ресурси UI и компилирания Tailwind както всяка страница, и преди redirect_canonical с приоритет 10. Обработчик, който сам визуализира цял документ, трябва да се изпълнява и след Assets::BUFFER_PRIORITY, иначе тази обработка се пропуска. Пътищата в urls (по подразбиране самият път на маршрута, ако той не е маршрут с префикс) се добавят към компилациите за статично предварително визуализиране, а Virtual_Routes::urls() ги връща като абсолютни URL адреси за карта на сайта. Virtual_Routes::match( $path ) разрешава път по същия начин като заявка.

Поведение при синхронизиране

Публикациите на страници се променят само чрез изрична операция за синхронизиране:

Обвивка
wp bs pages sync

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

Обвивка
wp bs pages sync --authoritative --full

Обикновените заявки от frontend частта, администрацията, AJAX, REST, cron и общите заявки за начално зареждане WP-CLI не откриват всички страници, не извличат управлявания списък за съгласуване и не записват публикации на страници. Те използват вече синхронизираните публикации WordPress, както и компактната конфигурация за колекции и шаблони на типове публикации, запазена при последната изрична операция. При първоначално инсталиране или надстройване може еднократно да се прегледат манифестите на колекциите, за да се възстановят метаданните за маршрутизиране; това начално зареждане е само за четене и никога не синхронизира съдържание. Удостовереният и незадължителен endpoint за обновяване на 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.

При заявки от frontend частта Blockstudio зарежда регистъра на страниците от вече синхронизираните публикувани публикации. Черновите и частните страници са достъпни в контекста на администрацията и синхронизирането, но помощните функции на frontend частта зареждат само публикувани страници.

Съгласуване при внедряване

Blockstudio\Pages::reconcile() е входната точка за внедряване на PHP. Тя открива пълния желан списък, сравнява отпечатъците на източника и механизма за синхронизиране и връща машинночетим отчет:

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

Отчетът съдържа discovered, created, updated, unchanged, locked, preserved, removed, removedPages, failed, fullReconciliation, резултати за всяка страница, грешки при откриването и детерминиран sourceIdentity.

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

След парсването и обединяването по ключ, ако крайната публикация е идентична, не се извиква wp_update_post(), не се променя post_modified, не се създава ревизия и не се задействат хукове за актуализиране на публикацията. Резултатът е unchanged. Когато съдържанието на изходния файл се различава от съдържанието на блоковете, управлявано от редактора, preserved: true обозначава това решение, а общият брой preserved включва тази публикация. Новият отпечатък на изходния файл и управляваните метаданни все пак се записват, така че следващата синхронизация без промени да не прави нищо. preserved е допълнителен флаг, а не изключителен статус: страницата може да запази блоковото съдържание с ключове и едновременно с това да актуализира заглавие, определено от файла, или да добави друг блок.

authoritative: true може да изчисти заключване на Page Sync и заменя съдържанието с дефиницията от файла, вместо да запази съдържанието в редактора, свързано с ключове. Оставете го false при обикновено изрично синхронизиране. plan_valid: false, full: true, broad: true, липсваща предишна идентичност на източника или променен отпечатък на механизма за синхронизиране маркират операцията като пълно съгласуване (fullReconciliation в отчета). При всяка операция се сравнява пълният списък. Записите за преименуване Git са само подсказки за идентичността. Те никога не заместват сравнението на пълния списък.

При еднакви отпечатъци и непроменени пътища по време на изпълнение не се записват публикации или метаданни на публикации и не се задействат куки за актуализиране. Когато непроменен източник се премести в нова директория за издание, съгласуването обновява само съхранените пътища към шаблона, съдържанието, оформлението и директорията; то не актуализира post_content или времевия печат на последната промяна на публикацията. Липсващите управлявани страници се премахват само след като пълното съгласуване приключи без грешки при откриване или запис на страници.

Директното съгласуване чрез API не отбелязва внедряването като успешно. След активиране и проверка на съответстващия статичен артефакт и маршрутите запишете изрично върнатата идентичност:

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

wp bs pages sync съхранява върнатата идентичност след успешна операция. Обикновеното начално зареждане WP-CLI регистрира само съхранените типове публикации на колекциите и правила за пренаписване. То не открива и не синхронизира страници.

Фиксиране на ID на публикация

По подразбиране WordPress автоматично присвоява ID на публикациите. Ако дадена страница бъде изтрита и създадена отново, ID се променя и това нарушава външни препратки като менюта или твърдо зададени връзки.

Използвайте postId, за да фиксирате страницата към определено ID:

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

При създаване на страницата Blockstudio предава ID на WordPress чрез import_id. Ако ID е налично, WordPress го използва точно. Ако ID вече е заето от несвързана публикация, WordPress безшумно присвоява ново ID автоматично.

Когато търси съществуващи страници, Blockstudio първо проверява фиксираното ID, преди да провери метаданните или slug. Така, ако страница бъде изтрита и синхронизирана отново, тя получава същото ID.

Обединяване на блокове по ключ

По подразбиране, когато файл с шаблон се промени, Blockstudio заменя цялото съдържание на публикацията с новия шаблон. Това означава, че всички редакции в редактора WordPress се губят.

Добавете атрибут key към блоковете, за да запазите потребителските редакции при синхронизиране на шаблон. Когато шаблонът съдържа блокове с ключове, Blockstudio обединява промените в шаблона със съществуващото съдържание на публикацията, вместо да го заменя.

Добавяне на ключове

Използвайте атрибута key за всеки елемент HTML или елемент <block>:

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

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

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

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

Ключовете трябва да са уникални в целия шаблон. Един ключ защитава целия блок и цялото му съдържание. Не е необходимо да задавате ключове на отделните дъщерни елементи във вътрешността на родителски блок с ключ. Между актуализациите на шаблона блоковете с ключове могат да се преместват на произволна позиция или ниво на влагане, без да се губи потребителското им съдържание.

Ключовете работят по същия начин и за персонализирани блокове Blockstudio. key представлява структурни метаданни на Page Sync; стойностите на персонализираните полета остават обикновени атрибути Blockstudio. Когато редактор промени тези полета, последващо синхронизиране на шаблона запазва стойностите от редактора и същевременно прилага независимите промени в шаблона. Страниците, създадени в по-стари версии, при които ключът е в данните на персонализираното поле, се мигрират автоматично при следващото синхронизиране.

Как работи обединяването

Когато файл с шаблон се промени и страницата се синхронизира отново:

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

Примери

Потребителските редакции в блокове с ключ се запазват:

  1. Шаблонът дефинира <p key="intro">Default intro.</p>
  2. Потребителят редактира абзаца в редактора на „Персонализиран уводен текст.“
  3. Разработчикът актуализира шаблона, добавя нов блок и променя оформлението
  4. При синхронизиране: абзацът запазва „Персонализиран уводен текст.“, а новото оформление се прилага

Атрибутите от шаблона продължават да се прилагат:

  1. Шаблонът съдържа блок за корица с key="hero" и атрибут url
  2. Разработчикът променя атрибута url на корицата, за да използва ново фоново изображение
  3. При синхронизиране: прилага се новото фоново изображение, а редакциите на потребителя в съдържанието на корицата се запазват

Особени случаи

Ситуация Поведение
Добавяне на нов блок с ключ към шаблона Появява се с подразбиращото се съдържание от шаблона
Премахване на блок с ключ от шаблона Изтрива се от публикацията
Промяна на типа блок (същият ключ) Шаблонът се прилага изцяло, без обединяване на съдържанието
Дублирани ключове Второто срещане се третира като блок без ключ
Шаблонът няма ключове Пълна замяна (както и без ключове)
Принудително синхронизиране Пълна замяна; ключовете се игнорират
Заключена публикация Синхронизиране изобщо не се извършва

Комбиниране с контролите за редактиране

Ключовете, templateLock и blockEditingMode осигуряват прецизен контрол върху действията, които клиентите могат и не могат да извършват. Ето няколко често срещани модела на работа.

Напълно заключена страница

Разработчикът контролира всичко. Страницата е статично оформление, до което клиентите нямат достъп. Подходяща е за правни страници, общи условия или всяка страница, която трябва да се променя само чрез код.

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

Не са необходими ключове. Шаблонът е единственият източник на истина. При всяко синхронизиране страницата се презаписва изцяло.

Заключено оформление с редактируемо съдържание

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

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

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

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

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

Развиващ се шаблон със запазено съдържание

За страници, които се разрастват с времето. Разработчикът добавя нови секции към шаблона и при всяка синхронизация се добавя новото съдържание, без да се променя вече персонализираното от клиента.

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

При синхронизация се появяват новата секция с отзиви и бутонът. Промените на клиента по заглавието, въведението и услугите остават непокътнати.

Еднократно създаване на основа

Създайте страница с начална структура и след това я предайте изцяло. Задайте sync на false, така че обичайната синхронизация никога да не създава или актуализира страницата, и я създайте еднократно с Blockstudio\Pages::force_sync('blog'). След това страницата принадлежи изцяло на клиента.

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

wp bs pages sync пропуска тази страница, затова force_sync() я създава еднократно. След това клиентът може свободно да добавя, премахва и пренарежда блокове. Промените в шаблона се игнорират.

Свързвания на блокове

Алтернатива на обединяването по ключове е използването на WordPress core на свързванията на блокове API за свързване на блокове с метаданни на публикацията. Това не е функция на Blockstudio, а вградена функция на WordPress API. Blockstudio просто предава атрибута metadata към генерирания блоков код. Съдържанието се съхранява в метаданните на публикацията, а не в кода на блока, затова синхронизациите на шаблона могат свободно да презаписват кода, тъй като редакторът чете от метаданните, а не от innerHTML.

Предайте атрибута metadata към всеки елемент HTML или <block>:

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

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

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

Мета ключовете трябва да бъдат регистрирани с включена опция show_in_rest:

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

Ключове и свързвания

Аспект Ключове Свързвания
Съхранявано съдържание Код на блока (post_content) Мета данни на публикацията (wp_postmeta)
Запазва се при синхронизация на шаблона Да (обединява се по ключ) Да (данните се съхраняват в метаданните)
Може да се заявява чрез WP_Query Не Да (meta_query)
Налично в REST API Не Да
Изисква регистрация Не Да (register_post_meta)
Потребителят може да мести блокове Не (шаблонът налага отново структурата) Не (шаблонът налага отново структурата)

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

Шаблони за типове публикации

Използвайте templateFor, за да зададете страница като шаблон по подразбиране за тип публикация:

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

Всички нови публикации от този тип ще започват с дефинираната структура от блокове.

Персонализирани пътища

По подразбиране Blockstudio сканира get_template_directory() . '/pages'. Добавете допълнителни пътища с филтъра:

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

Интеграциите по време на изпълнение, които съставят файлове от няколко корена, могат да заменят сканирането на файловата система с логически източник за откриване. След това манифестите на страниците, оформленията, зареждащите модули и изходните шаблони се разрешават чрез логически път, дори когато избраните от тях файлове се намират в различни корени.

Филтри и действия

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

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

PHP API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вижте Съгласуване при внедряване за семантиката на аргументите, полетата в отчета и проверената граница на идентичността на източника.

Глобалните помощни функции са достъпни за шаблони и оформления:

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

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

Създаване на страници от файлове

Заключване на шаблони, режими за редактиране на блокове, обединяване по ключове и управление на съдържанието, което клиентите могат да редактират.