コンテンツへスキップ

ページ

ページはファイルベースのテンプレートで、同期すると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スラッグ
path string "." コレクション内の論理パス
order integer 0 同期された投稿のメニュー順
postType string "page" WordPress投稿タイプ
postStatus string "draft" 新規投稿のステータス(publish、draft、pending、private)
postId integer – ページを特定のWordPress投稿IDに固定
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、フロントマター、ローダーの各エントリーで認識されるキーには、blockEditingMode、collection、content、contentType、defaults、file、html、markdown、meta、name、order、path、postId、postStatus、postType、postTypeArgs、render、slug、template、templateFor、templateLock、titleがあります。ここに記載されていないキーは、ページのmeta配列に保存されます。

コンテンツソース

ページ定義は、どのWordPress投稿を存在させるかを決めます。コンテンツソースは、その投稿にどのブロックマークアップを書き込むかを決めます。

ページフォルダーにpage.jsonがある場合、Blockstudioは同じ階層にあるソースファイルを次の順に探します:

ファイル 用途
index.php HTML風のブロックマークアップをそのまま読み込みます(PHPコードは実行されません)
index.blade.php Bladeテンプレートのコンテンツ
index.twig Twigテンプレートのコンテンツ
index.md Markdownコンテンツ

page.jsonでは、同じ階層のファイルの代わりに、markdownまたはhtmlをインラインで指定することもできます:

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

コレクションでは、さらに2種類のソースモードを使用できます:

  • コレクションツリーから直接検出されるMarkdownファイル。
  • loader.phpから返されるローダーエントリー。

ローダーエントリーでは、contentTypeを使ってmarkdown、html、またはcontentを指定できます。また、ローカルのfileやtemplateを参照することもできます。contentTypeが明示的に設定されていない限り、ファイルやテンプレートのソースタイプは拡張子から推測されます。

サポートされるcontentTypeの値は、php、blade、twig、markdown、htmlです。MarkdownはまずHTMLに変換され、その後ネイティブなWordPressブロックに解析されます。PHP、Blade、Twig、HTMLソースは、通常のBlockstudioページパーサーを通ります。

コアブロックのクラス

HTML要素に指定されたclassがコアブロックにマッピングされると、その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ページ

文章をファイルに置きながら、同期後に編集可能なWordPressブロックコンテンツにする場合は、Markdownを使用します。同期中にMarkdownソースがブロックマークアップに変換されます。同期後の投稿に保存されるのはブロックであり、生のMarkdown本文ではありません。

Markdownには3つの使い方があります:

ソース フロントマター必須? 備考
単独のpages/example/index.md はい フロントマターでページを識別します。
page.jsonとindex.md いいえ page.jsonでページを定義し、Markdownでコンテンツを指定します。
コレクション内のMarkdown いいえ コレクションがファイルの場所からnameとpathを推測します。

フロントマターのない単独のindex.mdは、同期するページの識別情報がBlockstudioにないためスキップされます。コレクション内のMarkdownでは、コレクションマニフェストとファイルパスから識別情報を取得するため、フロントマターは不要です。

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でコンテンツを指定します。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では、フロントマターで上書きされない限り、ファイルパスが論理ページパスになります:

ファイル デフォルトパス
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

不明なフロントマターキーは、ページのmeta配列に保持されます。これにより、sectionやdescriptionなどのデータを追加し、PHPAPIから読み取れます。

MarkdownはGitHub Flavored Markdownとして解析されます。生のHTMLも使用でき、安全でないリンクは削除されます。明示的なIDのない見出しには安定したIDが割り当てられます。ネストされたYAMLフロントマターには、同梱のYAMLパーサーが必要です。

生のMarkdown

Markdownファイルソースでは、外部ツールやドキュメント利用者向けに元のソースMarkdownを公開できます。インラインのMarkdownにはソースファイルがないため、ブロックに同期されますが、生の.mdレスポンスは生成されません。

.mdサフィックスを付けてページをリクエストします(例:https://example.com/docs/reference.md)。または通常のページURLにAccept: text/markdownヘッダーを送信します:

シェル
curl -H "Accept: text/markdown" https://example.com/docs/reference/

フロントマターはレスポンスから取り除かれます。生のMarkdownリクエストが成功すると、Content-Type: text/markdown、X-Robots-Tag: noindex、および正規のLinkヘッダーがHTMLページに返されます。.mdのないルートは、実際の404を返します。

このネゴシエーションは静的プリレンダリングと連携します。Acceptヘッダーにtext/markdownを含むリクエストは、プリレンダーストアや早期配信用ドロップインから応答されず、WordPressとMarkdownハンドラーに届きます。プリレンダリングされたHTMLレスポンス、MarkdownもネゴシエートするページのHTML、およびAccept経由で応答されるMarkdownはVary: Acceptを送信するため、Varyを尊重するキャッシュは両者を区別できます。URLだけをキャッシュキーとするCDNでは、このようなリクエストのキャッシュを迂回する独自のルールが必要です。Pages::negotiates_markdown( $post_id )は、ページがMarkdownリクエストに応答するかどうかを報告します。

コレクションMarkdownでは、生のMarkdownに同じURL形式が使われます:

ページURL 生のMarkdownURL
/docs/ /docs.md
/docs/getting-started/ /docs/getting-started.md
/docs/guide/install/ /docs/guide/install.md

blockstudio/pages/serve_markdownフィルターを使うと、生のMarkdownレスポンスを無効にできます:

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

.mdURLがMarkdownを基盤とするページに解決されない場合、パスがページコレクション内にあるときに限り404を返します。どのコレクションにも属さない場合、Blockstudioはリクエストを変更せず、WordPressや他のプラグインに処理を任せます。

コンポーネントページ

コンポーネントページはブロックとして保存されず、ページレンダラーによってレンダリングされます。Blockstudioにはレンダラーが同梱されていません。テーマまたはプラグインが、page.tsx用のReactレンダラーなど、処理するエントリーファイルに対応するレンダラーを登録し、Blockstudioがページ、WordPress投稿、およびレンダリング済みのスロットコンテンツを渡して呼び出します。

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

renderは明示的に指定します。index.phpとpage.tsxがあるディレクトリでも、renderがなければ通常のページのままです。そのため、レンダラーを追加しても既存のページが二重にレンダリングされることはありません。形式は次のとおりです。

値 意味
"page.tsx" データローダーなしのエントリーのみ
{ "entry": "page.tsx", "data": "data.php" } エントリーとデータローダー
{ "entry": "page.tsx", "renderer": "react" } レンダラーIDを明示したエントリー
false コレクションのデフォルトでレンダラーが指定されていても、レンダラーを使用しない

パスはページディレクトリを基準に解決されます。ローダーエントリーの場合は、コレクションルートが基準です。blockstudio/pages/allow_external_loader_pathで許可されていない限り、探索元の範囲内に収める必要があります。rendererがない場合は、そのエントリーの拡張子に対応するレンダラーが使用されます。renderが存在しないエントリーやデータファイルを指定している場合、未知のレンダラーが指定されている場合、またはどのレンダラーも対応していない拡張子の場合は探索エラーとなり、何も削除される前に調整処理が失敗します。

同期で保存される内容

同期ではblockstudio/pageブロックが1つ保存されます。ページディレクトリにindex.*ソースもある場合、そのソースは通常のページソースと同様に解析され、ブロックの内部ブロック、つまりスロットになります。

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

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

WordPressが所有するショートコードなどのコンテンツは、スロットに保持します。[download_checkout]のようにショートコードだけで構成されるソースは、core/shortcodeブロックとして保存されるため、その出力の周囲に段落は追加されません。post_content内に保持されるので、has_shortcode()のチェック対象となり、キー付きスロットブロックは、キー付きブロックがネストされている場合と同様にエディターでの変更とマージされます。また、do_shortcodeが通常のthe_content優先度でショートコードを一度だけ展開します。これはレンダラーがショートコードを囲んだ後に行われます。

レンダリング定義は、移植可能なtheme:パスとして投稿とともに保存されます。ページのフィンガープリントには定義が含まれますが、エントリーやデータローダーのバイト列は含まれません。page.tsxまたはdata.phpを編集しても投稿は変更されず、レンダリングと静的プリレンダリンググラフを通じて訪問者に反映されます。このグラフにはエントリー、データローダー、およびレンダラーが報告するすべてのファイルが記録されます。

レンダラーの登録

blockstudio/pages/renderersアクションでレンダラーを登録します。このアクションは、最初の探索またはレンダリングより前にリクエストごとに1回実行されるため、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',
			)
		);
	}
);

レンダラーIDは小文字です。拡張子またはレイアウト名を所有できるレンダラーは1つだけで、layout.phpはBlockstudio独自のレイアウトのままです。呼び出し可能な関数には、次のリクエストが渡されます。

キー 値
kind page、またはレンダラーレイアウトの場合はlayout
renderer レンダラーID
entry エントリーの絶対パス
data データローダーの絶対パス、またはnull
page metaを含む正規化されたページデータ
post_id WordPress投稿ID
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 modules、圧縮、?ver)が適用され、ブロックアセットを出力するのと同じバッファーを通じてページに一度だけ出力されるため、事前レンダリングされたページにも含まれます。アセットは version を設定して、?ver の値を置き換えられます。レンダラーの外部にあるコードも Blockstudio\Assets::register_owner() を通じて同じ経路を利用でき、出力するマーカーコメントが返されます。

エディター

エディターでは、blockstudio/page にページのサーバーレンダリング済みプレビューが表示され、スロットは内側のブロックとして配置されます。このブロックはページの templateLock に従います。このブロックは挿入、複製、または別のブロック内へのネストができません。

ページコレクション

コレクションはpages.jsonマニフェストを含むフォルダーです。1つのコレクションスラッグの下に複数のページソースをまとめ、デフォルトを適用し、ネストしたパスをサポートします。また、専用の投稿タイプを自動的に登録できます。

コード
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 Blockstudio がコレクションの投稿タイプを登録する際に、register_post_type() に渡される引数。
defaults object コレクション内のすべてのページに適用される既定のページプロパティ。既定の render は、ページディレクトリにそのエントリーがある場合にのみ適用されます。
scope string collection(既定)または site。サイトコレクションを参照してください。
meta object カスタムコレクションメタデータ。不明なマニフェストキーも meta に保存されます。

コレクションページのパスは論理パスです。path: "guide/install"を持つページはguideの子として同期され、guideは該当する親ページが存在すればコレクションルートの子として同期されます。

階層型コレクションにネストされたページがあり、中間の親ソースが存在しない場合、Blockstudioはそのパスに空のコンテナページを生成し、WordPress階層を完全な状態に保ちます。page-attributesの親をサポートしない非階層型投稿タイプでは、空のコンテナは生成されません。保存されたコレクションパスでルーティングするため、installで終わるguide/installとsetup/installのようなネストしたパスも共存できます。

コレクションの投稿タイプとURL

コレクションマニフェストにpostTypeを設定すると、コレクション内のすべてのページがその投稿タイプに同期されます。defaults内で同じ値を繰り返し指定する必要はありません。個々のページでは、フロントマターまたはpage.jsonでpostTypeを引き続き上書きできます。

投稿タイプが存在しない場合、Blockstudioはshow_in_rest: true、ページ向けのエディター設定、コレクションスラッグを公開URLのベースとして登録します。登録引数はpostTypeArgsで上書きできます。登録済みコレクション投稿タイプまたはリライト引数が変更されると、コレクション投稿タイプのリライトルールは自動的に再生成されるため、WordPressパーマリンクを保存し直す必要はありません。

コレクションURLは、コレクションスラッグと各ページの論理pathを使います:

ソースパス 公開URL
path: "." /docs/
path: "getting-started" /docs/getting-started/
path: "guide/install" /docs/guide/install/

このURLモデルは、階層型と非階層型のどちらのコレクション投稿タイプでも機能します。Blockstudioは、/docs/docs/や/docs/docs/getting-started/のように重複したURLも、正規のURLへリダイレクトします。

コレクションページでは、同じURLで生のMarkdownを公開します(生のMarkdownを参照)。

コレクションをpostType: "page"からカスタム投稿タイプに変更すると、保存済みのページ識別情報が一致する場合、Blockstudioは同期済みコレクション投稿をその場で移行します。これにより、投稿ID、メタデータ、既存コンテンツが保持され、古い投稿タイプの投稿が重複することもありません。古くなったコレクション投稿は、blockstudio/pages/orphan_actionフィルターに従い、すべての投稿ステータスを対象にクリーンアップされます。

サイトコレクション

"scope": "site" を含むマニフェストは、その下にあるすべてのページをグループ化しますが、それらをコレクションページにはしません。サイトのページツリーのルートで使用すると、共通の既定値を適用し、blockstudio_page_tree( 'my-site' ) でサイトのページを一覧表示できます。

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

サイトコレクション内のページは、マニフェストがなくても元の識別情報をそのまま保ちます。そのため、既存のツリーにページを追加しても投稿行は更新されず、作成や破棄も発生しません。

  • キーはグローバルのままです。Pages::get_page( 'home' ) と保存済みページキーは引き続き一致します。
  • URLは引き続き WordPress のページURLです。コレクション用のリライトルール、パーマリンクフィルター、二重の 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 paths から検出されたすべての Markdown ページに適用するレンダリング定義。

簡略形式として、ローダーはページ配列のリストだけを返すこともできます。

ローダーのページエントリーでは、次の方法でコンテンツを指定できます:

形式 説明
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を含められます。page.jsonやMarkdownのフロントマターで指定されたnameの値を保持するには、パスオブジェクトでpreserveNamesをtrueに設定します。

パスオブジェクトのプロパティ:

プロパティ 型 説明
path string 検出するローカルディレクトリ。相対パスはコレクションのルートを基準に解決されます。
prefix string コレクション内で使用する任意の論理パス接頭辞。
preserveNames boolean 接頭辞付きパスから名前を生成せず、明示的なページ名を維持します。prefix が設定されている場合の既定値は false です。
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 のレスポンス、フロントマターは変わりません。同期では、解析済みブロックの代わりに、内側の HTML が変換後の Markdown となる blockstudio/page ブロックが1つ保存されます。コレクションがコンテンツをサニタイズする場合は、その際にサニタイズされるため、post_content はドキュメントのテキストを維持できます。レンダラーはこの HTML をスロットとして受け取り、page.content_path からソースを読み取れます。相対パスはコレクションのルートを基準に解決され、外部パスフィルターは他のパスと同じように適用されます。フロントマターで独自の render または render: false を設定しているページは除外されます。

レイアウト

layout.phpファイルは、ファイルベースのページのフロントエンド表示をラップします。WordPressに保存された同期済みのpost_contentを置き換えるものではなく、エディターのキャンバスもラップしません。レイアウトは単一ページのフロントエンドリクエストでのみ実行されます。

コレクションのすべてのフロントエンドページをラップするには、pages.jsonの隣にlayout.phpを配置します:

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();

コレクションに属さないネストされたページも、pagesツリー内で最も近い祖先のlayout.phpを継承できます。コレクションページでは、コレクションのルートレイアウトが各同期済み投稿に保存され、ページのフィンガープリントの一部として監視されるため、レイアウトの変更は次回の同期で反映されます。

レンダラーレイアウト

レイアウトには、レンダラーエントリーを指定することもできます。たとえば、layouts: ["layout.tsx"] を登録するレンダラーの layout.tsx などです。layout.php と同じ場所で検出され、隣にある任意の layout.data.php はデータローダーとして機能します。レンダリング時にレンダラーが受け取るのは kind: "layout" と、the_content の優先度で layout.php と同様に slot として渡される、レンダリング済みのページコンテンツです。1つのディレクトリに置けるのは 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" 編集不可。ブロックは完全に操作できなくなります

要素ごとの上書きは、任意の要素(<h1>、<p>、<div>など)または<block>要素にHTML属性を設定して行います。上書きされた要素の祖先コンテナーブロックは、子要素にアクセスできるよう自動的に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が含まれます。また、優先度10のredirect_canonicalより前に実行されます。ドキュメント全体を独自にレンダリングするハンドラーは、Assets::BUFFER_PRIORITYの後にも実行する必要があります。そうしないと、その処理がスキップされます。urls内のパス(デフォルトでは、プレフィックスルートでない場合はルートパス自体)が静的プリレンダービルドに追加され、Virtual_Routes::urls()がサイトマップ用に絶対URLとして返します。Virtual_Routes::match( $path )は、リクエストと同じ方法でパスを解決します。

同期の動作

ページ投稿は、明示的な同期操作でのみ変更されます:

シェル
wp bs pages sync

このコマンドはソース全体を検出し、変更された投稿を作成または更新し、確認済みの孤立ページを削除し、コレクションのルーティングとコンパイル済みのtemplateFor設定を更新して、変更内容を報告します。キー付きエディターコンテンツを保持せず、管理対象コンテンツを置き換えるには--authoritativeを追加します。保存されたソースIDにかかわらず処理を完全な再照合として報告するには--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を実行する必要があります。

手動編集後にページが上書きされないようにするには、page.jsonで"sync": falseを設定します。

ポータブルなソースの場所

同期されたテーマファイルは、絶対インストールパスではなくテーマ相対の場所として保存されます。子テーマのファイルと親テーマのファイルは、相対ファイル名が同じでも別々の識別情報を維持します。ページヘルパーは引き続き、現在のリクエストに対応する解決済みの絶対 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は生成されたページを削除し、ソースファイルがなくなった後も古いコレクションページが残らないようにします。デフォルトでは、孤立したコレクションページはゴミ箱に移動されます。trash、delete、またはkeepを返すにはblockstudio/pages/orphan_actionを使用します。

フロントエンドリクエストでは、Blockstudioは同期済みの公開投稿からページレジストリを読み込みます。下書きと非公開ページは管理画面と同期処理で利用できますが、フロントエンドヘルパーが読み込むのは公開ページのみです。

デプロイの再照合

Blockstudio\Pages::reconcile()はPHPデプロイのエントリーポイントです。デプロイ対象の全インベントリを検出し、ソースと同期エンジンのフィンガープリントを比較して、機械可読形式のレポートを返します:

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

レポートには、discovered、created、updated、unchanged、locked、preserved、removed、removedPages、failed、fullReconciliation、ページごとの結果、検出エラー、決定論的なsourceIdentityが含まれます。

ロックされたページにはstatus: "locked"があり、変更のないページとは別に集計されます。removedPagesには、削除された各ページのname、key、postId、実際のaction(trashまたはdelete)が記載されます。保持された投稿や、すでにゴミ箱にある投稿は、新たに削除された投稿として集計されません。CLIのテーブル出力にも、作成、更新、ロック、削除、コンテンツ保持の各ページと、その投稿 ID が記載されます。

解析とキーによるマージの後、最終的な投稿が同一であれば、wp_update_post()の呼び出し、post_modifiedの変更、リビジョンの作成、投稿更新フックの実行は行われません。結果はunchangedです。ソースのコンテンツがエディター管理のキー付きコンテンツと異なる場合、preserved: trueでその判断が示され、トップレベルのpreservedカウントに含まれます。新しいソースフィンガープリントと管理メタデータは引き続き記録されるため、次回以降の変更のない同期では何も行われません。preservedは追加のフラグであり、ステータスを排他的に示すものではありません。ページでは、キー付きコンテンツを維持しながら、ファイルが管理するタイトルを更新したり、別のブロックを追加したりできます。

authoritative: trueはPage Syncロックを解除し、キー付きエディターコンテンツを保持せずにファイル定義からコンテンツを置き換える場合があります。通常の明示的な同期ではfalseのままにします。plan_valid: false、full: true、broad: true、以前のソースIDがない場合、または同期エンジンのフィンガープリントが変更された場合、処理は完全な再照合(レポートのfullReconciliation)として扱われます。いずれの場合も、各処理でインベントリ全体を比較します。Gitの名前変更記録はIDのヒントにすぎず、インベントリ全体の比較に代わるものではありません。

フィンガープリントが一致し、実行時のパスにも変更がない場合、投稿やpostmetaへの書き込みは行われず、更新フックも実行されません。変更のないソースが新しいリリースディレクトリに移動した場合、再照合では保存済みのテンプレート、コンテンツ、レイアウト、ディレクトリの各パスのみを更新します。post_contentや投稿の更新日時は変更しません。管理対象ページの削除は、検出エラーやページ書き込みエラーなしで再照合全体が完了した後に限り行われます。

APIによる直接の再照合では、デプロイを成功として記録しません。対応する静的アーティファクトとルートを有効化して検証した後、返されたIDを明示的に保存します:

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

wp bs pages syncは、処理が成功した後に返されたIDを保存します。通常のWP-CLIブートストラップでは、保存済みのコレクション投稿タイプとリライト規則のみを登録します。ページの検出や同期は行いません。

投稿IDの固定

デフォルトでは、WordPressが投稿IDを自動で割り当てます。ページを削除して再作成するとIDが変わり、メニューやハードコードされたリンクなどの外部参照が壊れる可能性があります。

postIdを使うと、ページを特定のIDに固定できます:

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

ページの作成時にBlockstudioはimport_idを介してWordPressにIDを渡します。IDが利用可能であれば、WordPressはそのIDをそのまま使用します。無関係な投稿がすでにそのIDを使用している場合、WordPressは通知せずに別のIDを自動で割り当てます。

既存ページを検索するとき、Blockstudioはメタデータやスラッグを確認する前に固定IDを確認します。そのため、ページを削除して再同期すると同じIDが再び割り当てられます。

キー付きブロックのマージ

デフォルトでは、テンプレートファイルが変更されると、Blockstudioは投稿コンテンツ全体を新しいテンプレートで置き換えます。そのため、WordPressエディターで行った編集は失われます。

ブロックにkey属性を追加すると、テンプレートの同期後もユーザーの編集内容を保持できます。テンプレートにキー付きブロックがある場合、Blockstudioは投稿コンテンツ全体を置き換えず、テンプレートの変更を既存の投稿コンテンツにマージします。

キーの追加

任意のHTML要素または<block>要素にkey属性を使用します:

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. ユーザーがエディターで段落を「Custom intro text.」に編集する
  3. 開発者がテンプレートを更新し、新しいブロックを追加してレイアウトを変更する
  4. 同期後も段落の「Custom intro text.」は保持され、新しいレイアウトが適用される

テンプレートの属性は引き続き適用されます:

  1. テンプレートにkey="hero"とurl属性を持つカバーブロックがある
  2. 開発者がカバーのurl属性を新しい背景画像に変更する
  3. 同期後は新しい背景画像が適用され、カバー内でユーザーが編集したコンテンツは保持される

例外的なケース

ケース 動作
テンプレートに新しいキー付きブロックを追加 テンプレートのデフォルトコンテンツで表示されます
テンプレートからキー付きブロックを削除 投稿から削除されます
ブロックの種類が変わる(キーは同じ) テンプレートが全体に適用され、コンテンツはマージされません
キーが重複している 2つ目以降はキーなしとして扱われます
テンプレートにキーがない 全体が置き換えられます(キーがない場合と同じ動作です)
強制同期 全体が置き換えられ、キーは無視されます
ロックされた投稿 同期されません

編集コントロールとの組み合わせ

キー、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を追加し、2つ目のボタンを加えても)、キー付きセクションのクライアントのテキストは保持されます。

コンテンツを保持しながらテンプレートを進化させる

時間の経過とともにページを拡張する場合に適しています。開発者がテンプレートに新しいセクションを追加すると、クライアントがすでにカスタマイズした内容に触れずに、同期のたびに新しいコンテンツが追加されます。

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>

同期すると、新しいお客様の声セクションとボタンが表示されます。タイトル、冒頭部分、サービスに対するクライアントの編集内容は変更されません。

一度限りのひな形

最初の構成でページを作成したら、完全に引き渡します。falseで通常の同期によるページの作成や更新を無効にするため、syncを設定し、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コアのブロックバインディングAPIを使って、ブロックを投稿メタに接続できます。これはBlockstudioの機能ではなく、ネイティブのWordPressAPIです。Blockstudioはmetadata属性を生成されたブロックマークアップにそのまま渡します。コンテンツはブロックマークアップではなく投稿メタに保存されるため、エディターはinnerHTMLではなくメタデータから読み込み、テンプレート同期でマークアップを自由に上書きできます。

任意のHTML要素または<block>要素にmetadata属性を渡します:

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)
RESTAPIで利用可能 いいえ はい
登録が必要 いいえ はい(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 フィルター コレクション CPT のregister_post_type()引数を調整します。
blockstudio/pages/template_candidates フィルター ページソースの候補となるテンプレートファイル名を調整します。
blockstudio/pages/serve_markdown フィルター 生のMarkdownレスポンスを有効または無効にします。
blockstudio/pages/orphan_action フィルター 孤立データのクリーンアップにtrash、delete、keepのいずれかを返します。
blockstudio/pages/docs_allowed_html フィルター 生成されたMarkdownドキュメントコンテンツに許可するHTMLを調整します。
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()にページレンダラーを登録します。リクエストごとに1回実行されます。
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]);

引数の意味、レポートのフィールド、検証済みソースIDの境界については、デプロイ時の照合を参照してください。

テンプレートとレイアウトでは、次のグローバルヘルパー関数を使用できます。

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クラスには、個別のパーマリンクメソッドはありません。

ファイルベースのページを作成する

テンプレートのロック、ブロック編集モード、キー指定のマージ、クライアントが編集できる項目の制御について説明します。