コンテンツへスキップ

ブロックタグでテンプレートを組み立てる

プロジェクトにいくつかのブロックができると、テンプレート同士を組み合わせる必要が出てきます。featuresブロックで3つのカードを表示したり、ランディングページでボタンを内包するセクションを使ったりする場合です。それぞれにbs_render_block()を呼び出せますが、PHPの呼び出しと入れ子の配列で埋まったテンプレートは読みにくく、さらに入れ子にするのも困難です。

ブロックタグを使うと、出力したい場所にHTMLタグとしてブロックを記述できます:

HTML
<bs:acme-card title="Fast" text="Rendered on the server." />

同じタグでも、記述する場所によって意味が異なります。ブロックテンプレートや投稿コンテンツ内では、ブロックのレンダリング済みHTMLに置き換わります。ページ、パターン、またはSite Templateのソース内では、エディターに表示される実際のWordPressブロックになります。このガイドでは、いくつかのブロックを作成し、2通りの方法で組み合わせ、プロジェクトのプレフィックスで名前を短縮したうえで、その略記を移植可能な正式表記に戻す方法を説明します。

ブロック

小さなブロックが3つあれば十分です。まず、2つのフィールドを持つカードです:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/card",
  "title": "Card",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title", "default": "" },
      { "id": "text", "type": "textarea", "label": "Text", "default": "" }
    ]
  }
}
PHP
<article useBlockProps class="acme-card">
  <h3><?php echo esc_html( $a['title'] ); ?></h3>
  <p><?php echo esc_html( $a['text'] ); ?></p>
</article>

カードと同じ方法でheadingフィールドを宣言し、その中に配置したものを囲むセクションです:

PHP
<section useBlockProps class="acme-section">
  <h2><?php echo esc_html( $a['heading'] ); ?></h2>
  <InnerBlocks />
</section>

そして、別の名前空間acme-ui/buttonにあるボタンです。labelとhrefのフィールドを持ちます:

PHP
<a useBlockProps class="acme-button" href="<?php echo esc_url( $a['href'] ); ?>"><?php echo esc_html( $a['label'] ); ?></a>

ブロックテンプレート内のタグ

ブロックテンプレートではタグが自動的にレンダリングされます。設定は不要です。featuresブロックから2つのカードとコアの区切りを直接出力できます:

PHP
<div useBlockProps class="acme-features">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <block name="acme/card" title="Typed" text="Fields come from block.json." />
  <block name="core/separator" />
</div>

acme/featuresをレンダリングすると、次のようになります:

HTML
<!--blockstudio/acme/features--><div class="acme-features wp-block-acme-features">
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Typed</h3>
  <p>Fields come from block.json.</p>
</article>

  <hr class="wp-block-separator has-alpha-channel-opacity">
</div>

出力内の各Blockstudioブロックの前には<!--blockstudio/namespace/slug-->コメントが置かれます。ページバッファーがこのコメントをレスポンスから取り除きます。バッファーを経由しない出力には、bs_strip_render_markers()を使用してください。 2つの構文は同等です。<bs:acme-card>はタグ内にブロック名を記述し、<block name="acme/card">は属性として渡します。その他の属性はすべてフィールド値になるため、titleはカードテンプレートに$a['title']として渡されます。コアブロックも使用でき、組み込みのブロックレンダラーを通じてWordPressでレンダリングされます。

ペアタグと内部コンテンツ

ペアタグの子要素はブロックに渡されます。Blockstudioブロックの場合は<InnerBlocks />に入り、内側のタグから先にレンダリングされます:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-card title="Fast" text="Rendered on the server." />
  <bs:acme-ui-button label="Get started" href="/start" />
</bs:acme-section>
HTML
<!--blockstudio/acme/section--><section class="acme-section wp-block-acme-section">
  <h2>Why Acme</h2>
  <div>
  <!--blockstudio/acme/card--><article class="acme-card wp-block-acme-card">
  <h3>Fast</h3>
  <p>Rendered on the server.</p>
</article>

  <!--blockstudio/acme-ui/button--><a class="acme-button wp-block-acme-ui-button" href="/start">Get started</a>

</div>
</section>

タグ名からブロック名への変換

<bs:>タグ名にはスラッシュがないため、Blockstudioがスラッシュを探します。ハイフンを左から順にスラッシュへ置き換え、登録済みの最初の候補を使います。<bs:acme-card>は最初の候補でacme/cardに解決されます。<bs:acme-ui-button>はacme/ui-buttonを試しますが見つからず、その後acme-ui/buttonに解決されます。名前空間にハイフンが含まれていても、候補が両方とも存在しない限り、設定なしで動作します。

プレフィックスで名前を短縮する

<bs:acme-ui-button>は正確ですが長い名前です。プロジェクトのプレフィックスを使うと、短いタグのプレフィックスを1つ以上の名前空間に対応付けられます。blockstudio.jsonで設定します:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "blockTags": {
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    }
  }
}

または、PHPから同じ対応表を登録します:

PHP
add_filter( 'blockstudio/block_tags/prefixes', function ( $prefixes ) {
	$prefixes['acme'] = array( 'acme' );
	$prefixes['ui']   = array( 'acme-ui' );

	return $prefixes;
} );

これで<acme-card>はacme/cardに、<ui-button>はacme-ui/buttonに解決されます。プレフィックスに複数の名前空間がある場合は、順番に試し、最初に登録されたブロックが使われます。これにより、同じスラッグを持つライブラリのブロックよりプロジェクトのブロックを優先できます。

プレフィックスは組み合わせることもできます。<acme-ui-button>はまずacme/ui-buttonを試します。そのブロックは存在しませんが、タグの残りの部分であるui-button自体が登録済みのプレフィックスタグなので、解決処理はacme-ui/buttonへ進みます。直接一致するものがあれば、常に入れ子の一致より優先されます。

HTML
<bs:acme-section heading="Why Acme">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

これは上記の正式表記とまったく同じHTMLをレンダリングします。

プレフィックスにはいくつかのルールがあります:

  • プレフィックスには小文字の英字と数字を使い、英字で始めます。ハイフンは使えません。
  • 登録済みブロックに解決されないプレフィックスタグは、<acme-missing title="x" />のように記述されたまま出力に残ります。
  • blockstudio/block_tags/tag_aliasesフィルターによる完全一致のエイリアスは、プレフィックスより優先されます。エイリアスはハイフン付きのタグ1つをブロック1つに対応付けます。たとえば$aliases['acme-cta'] = 'acme-ui/button';を設定すると、<acme-cta>がボタンとしてレンダリングされます。

プレフィックスとエイリアスのタグは、Blockstudio 7.5から<bs:>や<block>のタグと同様にブロックテンプレート内でレンダリングされます。

属性

フィールドIDと一致する属性はフィールド値になります。2つのプレフィックスには別の機能があります:

  • data-*属性は、レンダリングされたブロックのルート要素にコピーされます。
  • html-*属性は、プレフィックスを取り除いてルート要素にコピーされます。たとえばhtml-id="intro"はid="intro"になります。
HTML
<bs:acme-card title="Hi" text="There" data-track="card" html-id="intro" html-class="featured" />
HTML
<article data-track="card" id="intro" class="featured">
  <h3>Hi</h3>
  <p>There</p>
</article>

html-classは属性を設定するもので、値を追加するものではありません。ブロック自身のacme-card wp-block-acme-cardクラスは失われます。呼び出し元からブロックにクラスを追加する場合は、そのためのフィールドを宣言してテンプレート内で結合してください。

宣言済みフィールドではないその他の属性は削除されます。<bs:acme-card>にプレーンなclass="wide"があっても、カードはその属性なしでレンダリングされます。WP_DEBUGが有効な場合、Blockstudio 7.7は_doing_it_wrong()通知でそのような属性を報告します。

ページソース内の同じタグ

ファイルベースのページ、パターン、Site Templateでは、タグはレンダリングされません。ソースの解析時にブロックへ変換されるため、エディターに表示されます。このページソースは:

HTML
<bs:acme-section heading="Why Acme">
  <p>Everything below is a real block.</p>
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</bs:acme-section>

次のブロックマークアップに解析されます(読みやすいよう改行を追加しています):

HTML
<!-- wp:acme/section {"blockstudio":{"attributes":{"heading":"Why Acme"}}} -->
<!-- wp:paragraph --><p>Everything below is a real block.</p><!-- /wp:paragraph -->
<!-- wp:acme/card {"blockstudio":{"attributes":{"title":"Fast","text":"Rendered on the server."}}} /-->
<!-- wp:acme-ui/button {"blockstudio":{"attributes":{"label":"Get started","href":"/start"}}} /-->
<!-- /wp:acme/section -->

フィールド値はblockstudio.attributesに格納されます。これはBlockstudioブロックが値を保持する場所です。段落と2つの内部ブロックはセクションの内部ブロックになります。プレフィックスとエイリアスはテンプレートと同じように解決されます。

投稿コンテンツ内のタグ

エディターで作成したコンテンツやウィジェットに保存されたコンテンツは、既定ではスキャンされません。blockstudio.jsonでページ単位のレンダリングを有効にします:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

すると、the_contentとwidget_text内のタグが優先度5でレンダリングされます。同じスイッチで、任意の文字列内のタグをレンダリングするフィルターも登録されます:

PHP
$html = apply_filters( 'blockstudio/block_tags/render', $content );

fnmatch()ワイルドカードを受け付け、すべての構文と両方のレンダリング方式に適用されるallowとdenyのパターンを使って、レンダリング可能なタグを制限します:

JSON
{
  "blockTags": {
    "enabled": true,
    "deny": ["acme-ui/*"]
  }
}

このルールを設定すると、<acme-ui-button>と<bs:acme-ui-button>はレンダリングされず、そのまま出力に残ります。denyはallowより優先されます。blockstudio/block_tags/allowとblockstudio/block_tags/denyのフィルターは、PHPから同じリストを変更します。

解析では正式表記を検証する

PHPStan拡張機能は、PHP、Twig、Bladeのテンプレート内にあるブロックタグを検証します。フィールド名やブロック名の誤記は、解決先のブロック名とともに報告されます:

Text
  3      Block tag "acme/card" has unknown attribute "txt" in index.php
         🪪  blockstudio.blockTag.attribute
  4      Block tag references unknown block "acme/cards" in index.php
         🪪  blockstudio.blockTag.unknown

7.6では<bs:>と<block>のタグが対象です。<acme-card txt="...">のようなプレフィックスタグは検証されません。Blockstudio 7.7では、プレフィックスタグ、ページソース、マッピングされたHTML要素にもルールが適用され、タグから転送できるグローバル属性がヒントに表示されます。

略記を正式表記に移行する

プレフィックスとエイリアスのタグは、プロジェクト内で便利に使うためのものです。プロジェクトのフィルターと設定が読み込まれる場所でしか解決されないため、別のプロジェクトやブロックライブラリにテンプレートをコピーしたり、コーディングエージェントのコンテキストに渡したりすると、意味が失われます。<bs:namespace-slug>は実際のブロック名を記録し、どこでも解決できるため、Blockstudioのサンプル、診断、生成出力でも使われています。

独立したコマンドで略記を正式表記に書き換えられます。エイリアス、存在しなくなったブロックのタグ、コードサンプル内の例など、ソースに短縮形が残っているプロジェクトを例にします:

PHP
<div useBlockProps class="acme-features">
  <acme-card title="Fast" text="Rendered on the server." />
  <acme-ui-button label="Get started" href="/start" />
</div>
PHP
<acme-section heading="Why Acme">
  <acme-cta label="Talk to us" href="/contact" />
  <acme-quote text="Missing block" />
</acme-section>
<pre><code>&lt;acme-card /&gt; <acme-card title="Example" /></code></pre>

コマンドはWordPressを読み込まないため、スキャン対象のツリー外に置かれたプロジェクト設定をJSONファイルとして指定します:

JSON
{ "acme": ["acme"], "ui": ["acme-ui"] }
JSON
["acme/card", "acme/section", "acme/features", "acme-ui/button"]
JSON
{ "acme-cta": "acme-ui/button" }

まずはドライランから始めます。これが既定の動作です:

シェル
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/acme-tags/prefixes.json \
  --known-blocks=/tmp/acme-tags/blocks.json \
  --aliases=/tmp/acme-tags/aliases.json \
  --report=/tmp/acme-tags/report.json \
  --dry-run
Text
Report: /tmp/acme-tags/report.json
Dry run: 2 files, 2 changed, 5 replacements, 1 unknown, 0 ambiguous, 1 manual.

レポートには、適用されるすべての対応関係と、推測できないすべてのケースが表示されます:

JSON
{
  "mappings": [
    { "legacy": "acme-card", "canonical": "bs:acme-card", "block": "acme/card", "occurrences": 1 },
    { "legacy": "acme-cta", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 },
    { "legacy": "acme-section", "canonical": "bs:acme-section", "block": "acme/section", "occurrences": 2 },
    { "legacy": "acme-ui-button", "canonical": "bs:acme-ui-button", "block": "acme-ui/button", "occurrences": 1 }
  ],
  "unknown": [
    { "path": "pages/home/index.php", "line": 3, "column": 4, "tag": "acme-quote", "reason": "no-known-block" }
  ],
  "manual": [
    { "path": "pages/home/index.php", "line": 5, "column": 33, "tag": "acme-card", "reason": "code-sample" }
  ]
}

ここではレポートの一部を示しています。設定と各ファイルの変更前後のハッシュも記録されます。セクションの開始タグと終了タグは2つの出現箇所として数えられます。acme-quoteはacmeのプレフィックスに一致しますが、既知のブロック名ではないため不明です。<pre><code>内のacme-cardはマークアップではなく例なので、手動確認の対象として報告され、書き換えられません。HTMLコメントとインラインコードも同様です。

不明、曖昧、または動的なタグが残っていると、適用は拒否されます:

Text
Error: Unresolved tags remain; no files were written. Review a dry-run report or pass --allow-unresolved.

コマンドは2で終了します。ここでは不明なタグを削除して修正し、--dry-runではなく--applyを指定して実行します:

Text
Applied: 2 files, 2 changed, 5 replacements, 0 unknown, 0 ambiguous, 1 manual.

タグ名だけが変わります。属性はバイト単位でそのまま保持されます:

HTML
<bs:acme-section heading="Why Acme">
  <bs:acme-ui-button label="Talk to us" href="/contact" />
</bs:acme-section>

結果に対してドライランを再実行すると、0 changed, 0 replacementsが報告されます。その後もプレフィックスを登録したままにできるので、短縮形を使っている別のブランチに影響はありません。

次のステップ