コンテンツへスキップ

ファイルから作る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のどこに配置するかを指定します。

JSON
{
  "slug": "header",
  "title": "Header",
  "description": "Site header with logo and navigation",
  "area": "header"
}

ソースには、Blockstudioのページやパターンと同じ構文を使います。<div>はグループブロックになり、属性はブロック属性になります。また、<block>要素からは登録済みの任意のブロックを生成できます。

PHP
<div layout='{"type":"flex","justifyContent":"space-between"}'>
  <block name="core/site-title" />
  <block name="core/navigation" overlayMenu="mobile" />
</div>

Blockstudioはこれを次のブロックマークアップにコンパイルします。

HTML
<!-- 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 />タグ、設定済みのタグプレフィックスはいずれも、そのブロックのブロックコメントにコンパイルされます。

パーツは段落1つだけでも構いません。これはindex.htmlを使い、ソースがプログラムではなくマークアップであることを示しています。

JSON
{
  "slug": "footer",
  "title": "Footer",
  "area": "footer"
}
HTML
<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がその前に付くことはありません。

JSON
{
  "slug": "front-page",
  "title": "Front Page",
  "description": "Homepage template"
}
PHP
<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" />

シングル投稿テンプレートも、投稿ブロックを使って同じ形式で作成します。

JSON
{
  "slug": "single",
  "title": "Single Post"
}
PHP
<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" />

コンパイル後のシングルテンプレート:

HTML
<!-- 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で適用対象の投稿タイプを指定すると、編集者がテンプレート選択欄から選べるようになります。

JSON
{
  "slug": "page-landing",
  "title": "Landing Page",
  "description": "Full-width page without a header",
  "postTypes": ["page"]
}
PHP
<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を持つヘッダーパーツを返します。

参照順序は次のとおりです。

  1. データベースに保存されたSite Editorのカスタマイズ。
  2. 有効なテーマ内のネイティブな.htmlファイル。
  3. Blockstudioのファイルベースのソース。
  4. 親テーマまたはプラグインのフォールバック。

この優先順位なら、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クラスはソースを読み込んでコンパイルします。テストやデプロイ時の確認に便利です。

PHP
$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()で確認できます。

PHP
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors   = Blockstudio\Site_Templates::selection_errors( 'templates' );

その他のフォルダーを追加

Blockstudioソースをネイティブテンプレートと分ける場合や、プラグインから提供する場合は、フィルターを使って検出ルートを追加します。

PHP
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が選ぶテーマレイアウト(ヘッダー、フッター、シングル、アーカイブ) サイトテンプレートとパーツ
コンテンツをファイルに保存する、ルーティング可能なページ ファイルベースのページ
編集者が挿入できる再利用可能なセクション パターン

テンプレートは投稿を作りません。ページが投稿を作ります。たとえばドキュメントセクションはページのコレクションであり、ここで作成したテンプレートを使って投稿をレンダリングできます。

次のステップ