ファイルから作るSite Editorテンプレートとパーツ
ブロックテーマでは、レイアウトをtemplates/*.htmlとparts/*.htmlで定義します。
<!-- wp:template-part {"slug":"header"} /-->のようなシリアライズ済みブロックコメントを含むファイルです。
手作業で書くのは大変なので、通常はSite Editorで作成してエクスポートします。しかし、2人が同じテンプレートを編集したり、レビュー担当者がHTML内のコメントにあるエスケープ済みJSONの差分を読んだりするのは厄介です。
Blockstudioを使うと、ファイルベースのページと同じようにテンプレートを作成できます。小さなJSONマニフェストと、HTML風マークアップのソースファイルを含むフォルダーを用意し、通常の要素、<block>タグ、独自のBlockstudioブロックを使います。
Blockstudioがソースをネイティブのブロックマークアップにコンパイルし、テーマファイルとしてWordPressに渡します。Site Editorはこれまでどおり機能します。ユーザーはテンプレートをカスタマイズでき、リセットするとファイル版に戻ります。
このガイドでは、ヘッダーとフッターのパーツ、フロントページとシングルのテンプレート、さらに編集者がページ用に選べるカスタムテンプレートを作成し、WordPressによる解決方法を紹介します。
フォルダー構成
テンプレートはtemplates/に、テンプレートパーツはparts/に置きます。それぞれ、マニフェストとソースファイル1つを含むフォルダーです。
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
これらは、ブロックテーマ用にWordPressが読み込むtemplates/とparts/のフォルダーです。Blockstudioはまず有効なテーマをスキャンし、次に親テーマをスキャンします。template.jsonまたはpart.jsonを含むフォルダーはBlockstudioソースです。その隣にある通常の.htmlファイルは、引き続きネイティブのWordPressテンプレートとして扱われます。
ソースファイルはindex.php、index.blade.php、index.twig、index.htmlのいずれかで、この順に確認されます。TwigにはTimberが、Bladeにはレンダラーパッケージが必要です。詳しくはテンプレートエンジンをご覧ください。
ステップ1:ヘッダーパーツ
すべてのパーツにpart.jsonが必要です。areaで、パーツをSite Editorのどこに配置するかを指定します。
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
ソースには、Blockstudioのページやパターンと同じ構文を使います。<div>はグループブロックになり、属性はブロック属性になります。また、<block>要素からは登録済みの任意のブロックを生成できます。
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
Blockstudioはこれを次のブロックマークアップにコンパイルします。
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
これは、手作業で書く場合と同じ内容です。独自のブロックも同様に機能します。<block name="acme/announcement" />、<bs:acme-announcement />タグ、設定済みのタグプレフィックスはいずれも、そのブロックのブロックコメントにコンパイルされます。
ステップ2:フッターパーツ
パーツは段落1つだけでも構いません。これはindex.htmlを使い、ソースがプログラムではなくマークアップであることを示しています。
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
<!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->にコンパイルされます。
ステップ3:フロントページとシングルのテンプレート
テンプレートにはtemplate.jsonを使います。slugには、front-page、single、page、archive、404、single-productなど、テンプレート階層にある正確なWordPress名を指定する必要があります。Blockstudioがその前に付くことはありません。
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
シングル投稿テンプレートも、投稿ブロックを使って同じ形式で作成します。
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
コンパイル後のシングルテンプレート:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
<main>はtagName: "main"を持つグループブロックになり、テンプレートパーツブロックはステップ1と2のパーツをスラッグで参照します。WordPressがテンプレートをレンダリングすると、参照先はファイルベースのパーツに解決されます。そのためフロントページの出力は、サイトタイトルとナビゲーションを含む<header class="wp-block-template-part">で始まり、フッターの段落を含む<footer class="wp-block-template-part">で終わります。
ステップ4:ページ用のカスタムテンプレート
スラッグがテンプレート階層に含まれないテンプレートは、カスタムテンプレートです。postTypesで適用対象の投稿タイプを指定すると、編集者がテンプレート選択欄から選べるようになります。
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
get_block_templates( array( 'post_type' => 'page' ), 'wp_template' )にpage-landingが含まれるようになり、テンプレートオブジェクトにはpost_types: ["page"]が設定されます。
ソースは1度だけコンパイル
ソースはリクエストごとではなく、一度だけ読み込まれてブロックマークアップにコンパイルされます。現在の投稿やリクエストのコンテキストはありません。index.phpはマークアップとして読み込まれるため、その中のPHPコードは実行されず、<?php echo get_bloginfo( 'name' ); ?>は何もコンパイルしません。リクエストに依存する処理は、実行時にレンダリングするブロックに記述してください。サイト名を出力する代わりにcore/site-titleを、the_title()の代わりにcore/post-titleを使うか、独自の動的なBlockstudioブロックを使います。
コンパイル結果はファイル監視メタデータとともにキャッシュされます。マニフェストまたはソースファイルを編集すると、その項目のキャッシュ内容が無効になり、次のリクエストで別途ビルドせずに変更が反映されます。
WordPressによるファイルの認識方法
Blockstudioは、テーマテンプレートでWordPressが使うものと同じ検索処理に組み込まれます。get_block_templates()では、ファイルベースのテンプレートがネイティブのテーマファイルと同様にsource: "theme"とorigin: "theme"を持つ項目として表示されます。また、get_block_template( 'acme//header', 'wp_template_part' )はareaを持つヘッダーパーツを返します。
参照順序は次のとおりです。
- データベースに保存されたSite Editorのカスタマイズ。
- 有効なテーマ内のネイティブな
.htmlファイル。 - Blockstudioのファイルベースのソース。
- 親テーマまたはプラグインのフォールバック。
この優先順位なら、Site Editorのワークフローを維持できます。ユーザーがフッターを編集して保存すると、get_block_template()はwp_template_part投稿を保存し、WordPressはsource: "custom"を使ってそのカスタマイズを返します。
カスタマイズが存在する間は、parts/footer/index.htmlへの変更は反映されません。ユーザーがパーツをリセットするか投稿が削除されると、検索結果はファイルにフォールバックし、最新のコンパイル済みソースを再び返します。
Blockstudioは、Site Editorでの編集内容をファイルに書き戻しません。変更を新しい既定値にする場合は、ソースファイルにコピーしてからカスタマイズをリセットしてください。
入れ子のindex.htmlとスラッグ
WordPressは、templates/とparts/にある.htmlファイルを再帰的に検出します。そのため、index.htmlを使うマニフェストフォルダー(parts/footer/index.htmlなど)は、パスから導出されたスラッグfooter/indexを持つネイティブパーツとしても表示されます。Blockstudio 7.6.6以降、マニフェストが管理するindex.htmlは宣言されたスラッグでのみ公開されるため、Site Editorにはフッターが1つだけ表示されます。マニフェストのない入れ子の.htmlファイルはそのまま残ります。
PHPからテンプレートを確認
Blockstudio\Site_Templatesクラスはソースを読み込んでコンパイルします。テストやデプロイ時の確認に便利です。
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
各項目には、slug、title、description、type(wp_templateまたはwp_template_part)、status、source_type、テンプレートの場合はpostTypes、パーツの場合はarea、meta、そしてコンパイル済みのcontentが含まれます。リストを渡すと、選択した項目だけをコンパイルできます。その選択項目の問題はselection_errors()で確認できます。
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
その他のフォルダーを追加
Blockstudioソースをネイティブテンプレートと分ける場合や、プラグインから提供する場合は、フィルターを使って検出ルートを追加します。
add_filter( 'blockstudio/site_templates/template_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
} );
add_filter( 'blockstudio/site_templates/part_paths', function ( $paths ) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
} );
blockstudio/site_templates/template_contentとpart_contentのフィルターは、ソースを解析する前に調整します。blockstudio/site_templates/parserは、項目ごとにパーサーを置き換えます。全リストはサイトテンプレートのフック一覧をご覧ください。
使い分け
| 用途 | 使用する機能 |
|---|---|
| URL用にWordPressが選ぶテーマレイアウト(ヘッダー、フッター、シングル、アーカイブ) | サイトテンプレートとパーツ |
| コンテンツをファイルに保存する、ルーティング可能なページ | ファイルベースのページ |
| 編集者が挿入できる再利用可能なセクション | パターン |
テンプレートは投稿を作りません。ページが投稿を作ります。たとえばドキュメントセクションはページのコレクションであり、ここで作成したテンプレートを使って投稿をレンダリングできます。
次のステップ
- サイトテンプレートのリファレンス:すべてのマニフェストプロパティ、PHPAPI、すべてのフック。
- ページとパターンの概要:テンプレートソースで使うHTMLパーサー、ブロックタグ、要素マッピング。
- ドキュメントサイトの構築:Markdown、ローダー、レイアウトを使ったページコレクション。