コンテンツへスキップ

サイトテンプレート

サイトテンプレートを使うと、ブロックテーマでWordPress wp_templateソースと wp_template_partソースを定義できます。構文はBlockstudioの ページやパターンと同じファイル優先形式です。

サイトエディターのテンプレート階層を通じてWordPressが選ぶテーマレイアウト(フロントページ、個別投稿、アーカイブ、検索、404ページ、ヘッダー、フッター、その他のテンプレートパーツ)を制御するには、サイトテンプレートを使います。

ページ、パターン、それともサイトテンプレート?

機能 作成されるもの 適した用途
ページ 投稿またはカスタム投稿タイプの項目 通常のコンテンツページ、ドキュメントページ、ランディングページ、ルートとして利用できるコンテンツ。
パターン ブロックパターン エディターが挿入する再利用可能なセクション。
サイトテンプレート wp_templateおよびwp_template_partのファイルソース サイトエディターとWordPressのテンプレート階層で制御するテーマレイアウト。

サイトテンプレートは通常のページを作成しません。ブロックテーマのテンプレートを解決する際にWordPressが使うファイルソースを提供します。ユーザーがサイトエディターでテンプレートをカスタマイズすると、WordPressがそのカスタマイズをデータベースに保存し、リセットされるまでファイルソースより優先されます。

フォルダー構成

完全なテンプレートはtemplates/に、テンプレートパーツはparts/に配置します。

Text
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は次の順序で使用します。

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

WordPressは.htmlファイルも再帰的に検出し、通常はパスから導出したスラッグ(header/indexなど)でネストされたindex.htmlを公開します。 そのファイルがBlockstudioマニフェストに属する場合、Blockstudioはパス由来の重複項目を削除し、マニフェストで宣言されたslugだけを公開します。 Blockstudioマニフェストを持たないネストされたネイティブ.htmlテンプレートには変更ありません。

ソースは一度だけコンパイルされ、ネイティブなWordPressブロックマークアップになります。現在のリクエストや投稿に依存させないでください。ランタイムの動作は動的ブロック内に記述します。

template.json

template.jsonは完全なサイトエディターテンプレートを定義します。

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がテンプレート階層で使う正確な名前は次のとおりです。

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

part.jsonはサイトエディターのテンプレートパーツを定義します。

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用のカスタムメタデータ。不明なマニフェストキーもここに保存されます。

マークアップの作成

サイトテンプレートのソースでは、ページやパターンと同じパーサーを使います。

PHP
<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が管理します。

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

  1. サイトエディターによるデータベースのカスタマイズ
  2. アクティブテーマのネイティブ.htmlファイル
  3. Blockstudioのファイルベースソース
  4. 親テーマまたはプラグインのフォールバック

ユーザーがサイトエディターでBlockstudioのファイルベーステンプレートを保存すると、WordPressは通常のwp_templateまたはwp_template_partのデータベース項目を作成します。 保存された項目は、その後のファイル変更より優先されます。カスタマイズをリセットまたは削除すると、最新のファイルベースソースが再び表示されます。

v1では、Blockstudioはサイトエディターでの編集内容をファイルに書き戻しません。

パフォーマンス

テンプレートの検出結果はリクエストごとにキャッシュされ、ファイル監視メタデータとともに永続化されます。 マニフェストまたはソースファイルを変更すると、コンパイル済みコンテンツのキャッシュが無効になります。 データベースのカスタマイズは上書きキャッシュされません。WordPressは常に最初にカスタマイズを確認します。

複数のルートからファイルを組み合わせるランタイム統合では、テンプレートとテンプレートパーツに論理ディスカバリーソースを指定できます。マニフェストと選択されたソーステンプレートは、1つの論理テーマツリーを保ちながら、異なる物理ルートに配置できます。

PHP API

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

正確なスラッグ、パス、またはソースパスだけを読み込んでコンパイルするには、リストを明示的に渡します。

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

引数を省略すると、レジストリ全体を扱う動作が維持されます。空のリストを渡すと項目は返されません。通常のスラッグやパスを指定すると、一致するディレクトリだけが検出対象になります。カスタムマニフェストスラッグではメタデータのスキャンが必要な場合がありますが、関係のないソースはコンパイルも返却もされません。

テンプレート用のヘルパー関数も使用できます。

PHP
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 アクション 再構築されたレジストリの永続化後に実行されます。

検出パスを追加または置き換える:

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

add_filter('blockstudio/site_templates/paths', function ($paths) {
    return $paths;
});

検出データをフィルターする:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

解析前にソースをフィルターする:

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

ソース候補またはパーサーを変更する:

PHP
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はキャッシュ再構築時のライフサイクルアクションです。レジストリキャッシュが有効な状態でヒットした場合は実行されません。