サイトテンプレート
サイトテンプレートを使うと、ブロックテーマでWordPress wp_templateソースと
wp_template_partソースを定義できます。構文はBlockstudioの
ページやパターンと同じファイル優先形式です。
サイトエディターのテンプレート階層を通じてWordPressが選ぶテーマレイアウト(フロントページ、個別投稿、アーカイブ、検索、404ページ、ヘッダー、フッター、その他のテンプレートパーツ)を制御するには、サイトテンプレートを使います。
ページ、パターン、それともサイトテンプレート?
| 機能 | 作成されるもの | 適した用途 |
|---|---|---|
| ページ | 投稿またはカスタム投稿タイプの項目 | 通常のコンテンツページ、ドキュメントページ、ランディングページ、ルートとして利用できるコンテンツ。 |
| パターン | ブロックパターン | エディターが挿入する再利用可能なセクション。 |
| サイトテンプレート | wp_templateおよびwp_template_partのファイルソース |
サイトエディターとWordPressのテンプレート階層で制御するテーマレイアウト。 |
サイトテンプレートは通常のページを作成しません。ブロックテーマのテンプレートを解決する際にWordPressが使うファイルソースを提供します。ユーザーがサイトエディターでテンプレートをカスタマイズすると、WordPressがそのカスタマイズをデータベースに保存し、リセットされるまでファイルソースより優先されます。
フォルダー構成
完全なテンプレートはtemplates/に、テンプレートパーツはparts/に配置します。
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
各フォルダーには、マニフェストとソースファイルが1つずつあります。
| ファイル | エンジン |
|---|---|
index.php |
HTML風のブロックマークアップをそのまま読み込みます(PHPコードは実行されません) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
HTML風のブロックマークアップ |
ソースファイルが複数ある場合、Blockstudioは次の順序で使用します。
index.phpindex.blade.phpindex.twigindex.html
WordPressは.htmlファイルも再帰的に検出し、通常はパスから導出したスラッグ(header/indexなど)でネストされたindex.htmlを公開します。
そのファイルがBlockstudioマニフェストに属する場合、Blockstudioはパス由来の重複項目を削除し、マニフェストで宣言されたslugだけを公開します。
Blockstudioマニフェストを持たないネストされたネイティブ.htmlテンプレートには変更ありません。
ソースは一度だけコンパイルされ、ネイティブなWordPressブロックマークアップになります。現在のリクエストや投稿に依存させないでください。ランタイムの動作は動的ブロック内に記述します。
template.json
template.jsonは完全なサイトエディターテンプレートを定義します。
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
プロパティ
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
slug / name |
string |
フォルダー名 | WordPressテンプレートのスラッグ。front-page、single、archive-product、404など、階層に合った正確なスラッグを使います。 |
title |
string |
スラッグから取得したタイトル | サイトエディターに表示するタイトル。 |
description |
string |
"" |
サイトエディターに表示する説明。 |
postTypes |
string[] |
[] |
カスタムテンプレートの投稿タイプ。コアの階層テンプレートでは省略できます。 |
source / template / file |
string |
自動検出されたインデックスファイル | テンプレートフォルダーからの相対パスで指定する省略可能なソースファイルパス。 |
status |
string |
"publish" |
テンプレートのステータス。 |
sync |
boolean |
false |
将来のデータベース実体化用に予約されています。v1ではユーザーのカスタマイズは上書きされません。 |
meta |
object |
{} |
ヘルパーAPI用のカスタムメタデータ。不明なマニフェストキーもここに保存されます。 |
テンプレートのスラッグに接頭辞は付きません。WordPressがテンプレート階層で使う正確な名前は次のとおりです。
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
part.jsonはサイトエディターのテンプレートパーツを定義します。
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
プロパティ
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
slug / name |
string |
フォルダー名 | WordPressテンプレートパーツのスラッグ。 |
title |
string |
スラッグから取得したタイトル | サイトエディターに表示するタイトル。 |
description |
string |
"" |
サイトエディターに表示する説明。 |
area |
string |
"uncategorized" |
テンプレートパーツの領域。一般的な値はheader、footer、sidebarです。 |
source / template / file |
string |
自動検出されたインデックスファイル | パーツフォルダーからの相対パスで指定する省略可能なソースファイルパス。 |
status |
string |
"publish" |
テンプレートパーツのステータス。 |
meta |
object |
{} |
ヘルパーAPI用のカスタムメタデータ。不明なマニフェストキーもここに保存されます。 |
マークアップの作成
サイトテンプレートのソースでは、ページやパターンと同じパーサーを使います。
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<p>This template is compiled from Blockstudio files.</p>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" />
</div>
<main>要素はcore/groupブロックになり、<main>としてレンダリングされます。core/post-contentブロックタグを含む子要素は、内側のブロックになります。次を使用できます。
<h1>、<p>、<ul>、<div>などの標準HTML要素と、<main>、<header>、<footer>、<article>、<aside>などのセクション要素<block name="namespace/block"><bs:namespace-block>- 設定済みのブロックタグ接頭辞
- Blockstudioブロックとコンポーネント
WordPressがコンパイル済みテンプレートをレンダリングすると、テンプレートパーツのブロックにはアクティブテーマの属性が付与されます。
サイトエディターでのカスタマイズ
Blockstudioがファイルソースを提供し、ユーザーのカスタマイズはWordPressが管理します。
参照順序は次のとおりです。
- サイトエディターによるデータベースのカスタマイズ
- アクティブテーマのネイティブ
.htmlファイル - Blockstudioのファイルベースソース
- 親テーマまたはプラグインのフォールバック
ユーザーがサイトエディターでBlockstudioのファイルベーステンプレートを保存すると、WordPressは通常のwp_templateまたはwp_template_partのデータベース項目を作成します。
保存された項目は、その後のファイル変更より優先されます。カスタマイズをリセットまたは削除すると、最新のファイルベースソースが再び表示されます。
v1では、Blockstudioはサイトエディターでの編集内容をファイルに書き戻しません。
パフォーマンス
テンプレートの検出結果はリクエストごとにキャッシュされ、ファイル監視メタデータとともに永続化されます。 マニフェストまたはソースファイルを変更すると、コンパイル済みコンテンツのキャッシュが無効になります。 データベースのカスタマイズは上書きキャッシュされません。WordPressは常に最初にカスタマイズを確認します。
複数のルートからファイルを組み合わせるランタイム統合では、テンプレートとテンプレートパーツに論理ディスカバリーソースを指定できます。マニフェストと選択されたソーステンプレートは、1つの論理テーマツリーを保ちながら、異なる物理ルートに配置できます。
PHP API
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();
$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');
$paths = Blockstudio\Site_Templates::get_paths();
正確なスラッグ、パス、またはソースパスだけを読み込んでコンパイルするには、リストを明示的に渡します。
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
引数を省略すると、レジストリ全体を扱う動作が維持されます。空のリストを渡すと項目は返されません。通常のスラッグやパスを指定すると、一致するディレクトリだけが検出対象になります。カスタムマニフェストスラッグではメタデータのスキャンが必要な場合がありますが、関係のないソースはコンパイルも返却もされません。
テンプレート用のヘルパー関数も使用できます。
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
フック
サイトテンプレートの拡張ポイント一覧:
| フック | 種類 | 説明 |
|---|---|---|
blockstudio/site_templates/template_paths |
フィルター | 完全なテンプレートの検出ルートを調整します。 |
blockstudio/site_templates/part_paths |
フィルター | テンプレートパーツの検出ルートを調整します。 |
blockstudio/site_templates/paths |
フィルター | templatesとpartsとして両方のパスリストを調整します。 |
blockstudio/site_templates/template_candidates |
フィルター | マニフェストのソースファイル候補を調整します。 |
blockstudio/site_templates/templates |
フィルター | レジストリAPIが返すテンプレートを調整します。 |
blockstudio/site_templates/parts |
フィルター | レジストリAPIが返すテンプレートパーツを調整します。 |
blockstudio/site_templates/template_content |
フィルター | 解析前にコンパイル済みの完全なテンプレートソースを調整します。 |
blockstudio/site_templates/part_content |
フィルター | 解析前にコンパイル済みのテンプレートパーツソースを調整します。 |
blockstudio/site_templates/parser |
フィルター | 1つの項目に対するHtml_Parserインスタンスを置き換えます。 |
blockstudio/site_templates/source_compiled |
アクション | 選択した1つのソースのコンパイル直前に実行されます。 |
blockstudio/site_templates/discovered |
アクション | キャッシュなしの検出とコンパイル処理後に実行されます。 |
blockstudio/site_templates/registered |
アクション | 再構築されたレジストリの永続化後に実行されます。 |
検出パスを追加または置き換える:
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;
});
add_filter('blockstudio/site_templates/paths', function ($paths) {
return $paths;
});
検出データをフィルターする:
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
解析前にソースをフィルターする:
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
return $content;
}, 10, 2);
add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
return $content;
}, 10, 2);
ソース候補またはパーサーを変更する:
add_filter(
'blockstudio/site_templates/template_candidates',
function ($candidates, $directory, $manifest) {
$candidates[] = $directory . '/template.custom.php';
return $candidates;
},
10,
3
);
add_filter(
'blockstudio/site_templates/parser',
function ($parser, $item) {
return $parser;
},
10,
2
);
discoveredとregisteredはキャッシュ再構築時のライフサイクルアクションです。レジストリキャッシュが有効な状態でヒットした場合は実行されません。