コンテンツへスキップ

プログラムによるレンダリング

Gutenberg がクライアント向けに編集しやすいウェブサイトを作る主要な手段となった今、必要なウェブサイト領域をすべてブロックとして作るのは理にかなっています。この方法で大半のニーズに対応できますが、高度なユーザーや特定の用途では、既存のブロックをエディターの外で使う必要があるかもしれません。

Blockstudioでは、ブロックをプログラムからレンダリングする方法を2つ用意しています。

  • PHP関数:PHPコードからレンダリングするbs_render_blockとbs_block
  • HTMLタグ:ページ内の任意の場所でブロックの出力に置き換わる<bs:block-name>タグ

インラインスタイル、スクリプト、スコープ付きスタイルなど、Blockstudio固有の機能はすべてサポートされています。

Islandsも、これらのレンダリング経路で機能します。bs_render_block()、bs_block()、またはブロックタグでレンダリングされた動的アイランドは、投稿コンテンツからレンダリングされたブロックと同じプレースホルダーマーカーを返します。そのマーカーがレスポンスに含まれると、フロントエンドのランタイムが挿入されます。

構造化された構成と完全なドキュメント

長期利用するツール、プレビュー、エクスポート、コンポーネントギャラリーには、バージョン管理されたBlockstudio\RenderAPIを使います。1つの宣言または順序付きリストを受け取り、出力を直接返します。

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

正規化後の標準宣言には、4つのキーがあります。

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

data、inner、innerBlocks、root、layers、exampleは入力時の便宜機能であり、正規化の際に取り除かれます。ネストされた宣言は、同じBlockstudioパイプラインを通じて再帰的にレンダリングされます。

Render::document()はschemaVersion、html、body、blocks、assets、warnings、errorsを返します。assetsの値は、head、footer、styles、scripts、modules、interactivity、ui、tailwindを区切ります。 ブロック一覧とアセットには、選択したテンプレートが参照する依存関係が含まれますが、無関係なアセットやエディター専用アセットは含まれません。

完全なドキュメントでは、bodyClasses/bodyAttributesを設定し、必要に応じてレンダリングされた本文をcontentElement、contentClasses、contentAttributesで囲めます。ラッパーに使えるのは安全な要素名に限られ、返されるbodyはラップされていないレンダリング済みコンテンツのままです。 headとfooterのオプションを使うと、信頼されたドキュメントマークアップをそれぞれの位置に追加でき、返されるアセットの依存関係にも含まれます。

すでにレンダリング済みのHTMLを囲むドキュメントを組み立てるには、既知のルートブロック名を指定します。

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

シリアライズ済みのWordPressブロックコンテンツにはRender::content()を使います。1回のリクエストで複数の独立したドキュメントをレンダリングする場合は、ドキュメントごとにBlockstudio\Batch_Render::reset()を呼び出します。Canvas::documents()はこれを自動的に行います。

ページ外でのレンダリング

Blockstudioは、レンダリングするすべてのブロックの前に<!--blockstudio/namespace/slug-->コメントを挿入します。フロントエンドのページでは、バッファーがこれらのコメントを読み取って存在するブロックを確認し、それらのアセットを読み込み、レスポンスの送信前にコメントを削除します。

このバッファーを通らない出力には、コメントが残ります。これはRESTレスポンス、フィード、AJAXハンドラー、およびHTMLの後に別の場所へ保存または送信するdo_blocks()、Render::content()、bs_render_block()に当てはまります。コメントを削除するにはbs_strip_render_markers()を使用してください:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

この関数は、登録済みのBlockstudioブロックのコメントを削除し、その他のHTMLコメントも含め、それ以外には一切手を加えません。ページバッファーが削除するものと同じマーカーを照合します。ブロック登録後(init以降)に呼び出してください。

バッファーを通るフロントエンドページにまだ出力されるマークアップは削除しないでください。ページが読み込むブロックアセットを判別するにはコメントが必要で、最後にBlockstudioがコメントを削除します。

コメントを削除してもアセットは追加されません。ブロックのCSSファイルとJavaScriptファイルは、ページバッファーによってのみ挿入されます。利用側でもアセットが必要な場合は、bs_block_assets()またはRender::document()を使用してください。

ブロックの調査

内部レジストリを読み取らずに解決済みのフィールド定義を取得するには、ブロック登録後(init以降)にbs_block_fields()を使用してください:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

戻り値は、属性フィルター、展開済みカスタムフィールド、オーバーライド、ネストされたグループ、タブ、リピーターを含む、登録済みフィールド定義の配列です。フィールドのないBlockstudioブロックは[]を返します。結果はコピーであり、変更しても登録済みブロックには影響しません。

これらは定義であり、保存済みの値ではありません。保存済みのマークアップを検証するには、個別のフィールド走査処理を用意せず、bs_validate_block()を使用してください。ブロックが受け付ける値を記述するには、bs_block_schema()を使用してください。WordPressが所有する属性は別に扱われます。

拡張で追加されたフィールドはbs_block_fields()には含まれません。取得するにはbs_block_extension_fields()を使用してください。ブロック名で拡張を照合するため、コアブロックやサードパーティ製ブロックにも使えます:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

戻り値には、bs_block_fields()と同じ構造で、一致したすべての拡張のフィールド定義が、拡張の登録順に並びます。拡張と一致しないブロックは[]を返します。拡張の値は、ブロック独自のフィールド値と同じattrs.blockstudio.attributesオブジェクトに保存されるため、すべてのIDが同じ名前空間を共有します。2つの拡張が同じIDを定義した場合、両方の定義が返され、同じ値を編集します。レンダリング時には、後から登録された拡張の定義が適用されます。

保存済みブロックの値をテンプレートが受け取る形で読み取るには、bs_block_values()を使用してください。

ブロックで検出されたCSSとJavaScriptを調べるには、bs_block_assets()を使用してください。ネストされたブロックや共有ランタイム依存関係を含む完全なプレビュー文書を取得するには、上記の説明に従ってRender::document()を使用してください。

保存済みの値を検証する

プログラムで生成またはインポートしたブロック属性を保存する前に確認するには、ブロック登録後(init以降)にbs_validate_block()を使用してください:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

attrs配列全体を渡してください。blockstudio.attributesだけでは不十分です。Blockstudioのレンダリングでは、宣言済みフィールドを最上位にも指定でき、両方が渡された場合はネストされた値が優先されます。コアブロックとサードパーティ製ブロックの拡張が読み取るのはblockstudio.attributesだけです。空のBlockstudioブロックは管理対象であり、nullではなく[]を返します。

検証は明示的に実行する読み取り専用の処理です。テンプレートのレンダリング、値の変更、投稿の保存、メディアの照会、populateコールバックの実行は行いません。保存、ページ同期、レンダリングの際に自動実行されることもありません。サニタイザーや認可チェックではなく、添付ファイルの存在を確認するものでもありません。

各検出結果には、次の固定キーが含まれます:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

ツールでは翻訳後のmessageではなく、codeを使用してください。sourceはblockまたは extensionです。パスにはストレージキーと、0始まりのリピーター行または選択肢の インデックスを使用し、先頭にスラッシュは付けません。キー内のリテラルな~と/は、~0および ~1としてエスケープされます。トップレベルのグループは子フィールドに接頭辞を付けます(cta_title)。匿名グループとタブは階層を追加しません。IDを持つグループが別のグループまたはリピーター内にある場合、ビルダーではサポートされないため、そのキーは受け付けられません。メッセージフィールドには保存値がありません。ファイルフィールドでは、<id>__sizeの付随フィールドが許可されます。 Blockstudioブロックのルートでは、管理用キーと、レンダリングされた要素に転送されるグローバルなHTML属性は未知のフィールドではありません。ただし、リピーター行の任意のキーやコアブロックの拡張が許可されるわけではありません。

コード 意味 expected
unknown_field このストレージキーを宣言する保持フィールドがありません。 既知のストレージキー。
unknown_option 選択値が既知の選択肢に含まれていません。 許可される選択肢の値。
wrong_type 保存された形式は、このフィールドではサポートされていません。 想定されるストレージの分類または型。
too_few_rows, too_many_rows リピーターが存在しますが、minまたはmaxの範囲外です。 行数の上限または下限。
definition_conflict 1つのキーに適用される定義間で、ストレージ形式が異なります。 各定義のソースとフィールド型。
shadowed_value ネストされた値が、異なるトップレベルフィールドの値を上書きしています。 優先されるネスト値。
extension_top_level テンプレートはトップレベルの値を読み取れますが、拡張バインディングからは読み取れません。 blockstudio/attributesで必要なパス。
unknown_attribute Blockstudioブロックのトップレベルキーはレンダリング経路で読み取られず、破棄されます。 登録済み属性名、拡張フィールド、およびblockstudio。
missing_container attributes、disabled、name、またはeditorがトップレベルに保存されていますが、blockstudioがありません。 blockstudioで必要なパス。
invalid_container blockstudioまたはblockstudio.attributesがオブジェクトではありません。 object。

unknown_fieldの検出メッセージには、3文字以内の編集で一致する、同じ階層の最も近い保存キーが示されます。これは未知の設定に関するルールです。This storage key is not declared by the block or its extensions. Did you mean "title"? expectedには、引き続きすべての既知のキーが表示されます。 照合では大文字と小文字を区別せず、そのコンテナ内の保存キーのみが対象です。 メッセージは翻訳されるため、連携機能ではメッセージ本文を解析せず、code、path、expectedを使用してください。

Blockstudioブロックのトップレベルキーが、登録済み属性(そのフィールド、WordPressがsupports、lock、metadata用に追加する属性)、対応する拡張のフィールド、blockstudio、管理用キー、または転送されるHTML属性のいずれでもない場合、テンプレートの実行前に破棄されます。このようなキーは、たとえばフィールドIDの入力ミスや、blockstudioラッパーなしで保存されたvaluesオブジェクトなど、ブロックがその値なしでレンダリングされる原因となるため、検出結果が報告されます。拡張フィールドのみを持つブロックでは、トップレベルキーはチェックされません。

受け付けられる形式はレンダリング時の動作に準じます。複数選択とチェックボックスには、リスト、1つの選択肢オブジェクト、または数値の0を含むインポート済みスカラー値を指定できます。数値文字列は数値として受け付けられます。ファイルには、添付ファイルID、IDオブジェクト、リスト、または文字列参照を指定できます。リンクとアイコンの値はオブジェクトである必要があり、カスタムフィールド型には登録済みの属性型が使用されます。 attributesフィールドには、空でないattribute名とスカラー値valueを持つペアのリストを格納します。data.mediaなどの任意のメタデータは保持されます。

レンダリング前に登録済みのトップレベル属性を検証するWordPressでは、blockstudio.attributes内で受け付けられる形式が拒否されることがあります。たとえば、"a"のラジオ値はネストされたオブジェクトでは機能しますが、トップレベルでは破棄されます。トップレベルでの登録型はobjectです。このような値はwrong_typeを発生させます。 エディターが書き込むものと同じ保存形式を使うには、ネストされたオブジェクトを使用してください。

フィールドがないことは必須エラーではありません。空のネスト値(null、false、''、 [])や無効化されたフィールドは、値のエラーを発生させません。明示的に空にしたリピーターはminに対して引き続きチェックされますが、存在しないリピーターや無効化されたリピーターはチェックされません。 トップレベルの空値がWordPressによって破棄され、空でないデフォルト値に戻される場合は報告されます。同じ値をネストされたオブジェクトに設定すると、値をクリアできます。 キーに保存値がない場合でも、定義の競合は報告されます。

静的な選択肢と登録時に解決済みのpopulate選択肢は、populateを再度実行せずにチェックされます。リモートのfetch選択肢と、{attributes.*}を含むpopulate引数はスキップされます。disableCustomColorsまたはdisableCustomGradientsが設定されていない場合、色とグラデーションの値はカスタムにできます。 このチェックの対象は保存値です。default、fallback、またはエディターの検証ルールは対象外です。

対象となるすべてのブロックに、対応する拡張フィールドが含まれます。レンダリング時と同様に、ブロックまたはそのルート拡張内では後の定義が優先されます。ブロック自身のフィールドと拡張フィールドは、同じキーの別々の定義として両方が適用されます。リピーター行では、レンダラーは各ソース内でIDが一致する最初のフィールドを読み取るため、その選択肢と上限・下限が適用されます。競合診断のため重複定義も保持されます。互換性のないストレージ形式は、後の重複定義がレンダリング時に読み取られない場合でもdefinition_conflictを発生させます。

この関数は1つのブロックをチェックします。ドキュメントの検証時はinnerBlocksを走査してください。同期パターンやその他の参照は自動的に展開されません。 ブロックを走査し、そのパスを報告します。wp bs blocks validateコマンドは、1つ以上の投稿に含まれるブロックを対象とします。

カスタムのレンダリング時リゾルバーを使うサイトでは、保存データを変更せずに検出結果を調整できます。

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

検出結果のリストを必ず返してください。[]を返すとブロックが受け入れられます。このフィルターが実行されるのは管理対象ブロックに限られ、nullの結果には適用されません。

保存値の記述

ブロック登録後(initまたはそれ以降)にbs_block_schema()を使用すると、ブロックが保存する値を記述できます。たとえば、ツールや AI 連携機能でブロックのマークアップを生成したり、RESTルートで入力を確認したりできます。

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

結果は、attrs.blockstudio.attributesに保存されるオブジェクトのJSON Schema です。ブロックのフィールドと一致する拡張機能のフィールドを対象とし、検証で使用する保存キーも含みます。トップレベルのグループでは子要素に接頭辞が付き、名前のないグループとタブでは階層が増えません。また、ファイルフィールドには<id>__sizeの関連項目が追加されます。リピーターは行オブジェクトのリストで、minとmaxのminItemsおよびmaxItemsが適用されます。additionalPropertiesはフィールド保存のルートとリピーターの各行でfalseです。リンクやカスタムオブジェクトなど、値がオブジェクトのフィールドには独自のメタデータを設定できます。フィールドのないブロックにはpropertiesがないため、一致するのは空のオブジェクトのみです。

各フィールドは、bs_validate_block()で受け付けられる標準形式で記述します。

フィールド Schema
text, textarea, richtext, wysiwyg, code, date, datetime, unit, classes, html-tag, block 文字列。
number, range 数値。minとmaxに基づくminimumとmaximumを含みます。
toggle 真偽値。
select, radio, checkbox オプション値。checkboxとmultipleでは、enumを含むオプション値のリストです。
color, gradient 文字列。disableCustomColorsまたはdisableCustomGradientsが設定されている場合はenumを含みます。
token 文字列のリスト。
files 0以上の整数の添付ファイル ID、またはmultipleを含む ID のリスト。
link url、title、opensInNewTabを含むオブジェクト。urlは必須です。
icon set、subSet、iconを含むオブジェクト。setとiconは必須です。
attributes 空でないattributeとスカラー値のvalueを含むオブジェクトのリスト。
repeater 行オブジェクトのリスト。
カスタムフィールド型 登録された属性型。

enumには、検証でチェックされるオプションが列挙されます。登録時に解決済みの静的オプションと populate オプションです。リモートのfetchオプションや、{attributes.*}を含む populate 引数にはenumがありません。保存形式が異なる定義を持つキーは除外されます。そのキーに保存された値はすべて検証で報告されるためです。ブロックフィールドと拡張フィールドで同じキーを使う場合、enumには両方が受け付ける値が列挙されます。共有リピーターでは子フィールドを組み合わせ、両方の定義のうち厳しい方の行数制限を適用します。リピーターの行内では、描画時と同様に、それぞれの定義元で ID が一致する最初のフィールドが適用されます。<id>__sizeという名前の明示的なフィールドは、自動追加されるファイルサイズの関連項目より優先されます。

閉じたフィールドで選択肢がない場合、または適用される2つのオプションセットに共通項がない場合、単一選択の標準値はnull、複数選択の標準値は空のリストになります。オプションリストが空でも、フィールドが制限なしになることはありません。リモートの選択肢と属性に依存する選択肢は制限されません。

フィールドのlabelはtitleに、helpはdescriptionになります。defaultは注釈として保持されます。Schema 自身のtitleはブロックタイトルです。フィールドが必須になることはなく、条件付きロジックも Schema には含まれません。

制約にはrest_validate_value_from_schema()がチェックするキーワードのみを使用するため、Schema はRESTルートまたはアビリティの入力 Schema としてそのまま使えます。

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

スキーマはフィールドごとに1つのフォームを記述しますが、検証ではオプションオブジェクト、数値文字列、IDオブジェクトなど、インポートされた形式も受け付けます。これはbs_validate_block()に取って代わるものではありません。定義の競合は設定上の問題であり、競合するキーが省略されていても検出結果が生じることがあります。検証フィルターでサイト固有のルールを適用することもできます。保存済みコンテンツの確認にはbs_validate_block()を使います。レンダリング時に独自のリゾルバーを使うサイトでは、blockstudio/blocks/attributes/schemaフィルターを使ってスキーマを調整できます。

PHP関数

データなし

最も簡単な形式では、ページにレンダリングするブロックのIDを1つ指定します。

PHP
bs_render_block('blockstudio/cta');

データあり

カスタムデータを使ってブロックをレンダリングするには、最初のパラメーターに単一の値ではなく配列を指定します。dataキーの値は、ブロックテンプレート内の$attributes変数と$a変数に渡されます。

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

ネスト

ブロックテンプレート内の$content変数とbs_block関数を組み合わせると、ブロックを互いにネストできます。

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

ブロックテンプレート内の$content変数の位置にボタンブロックがレンダリングされます。

bs_render_block()またはbs_block()でレンダリングされる埋め込みブロックは、親ブロックがエディターのプレビューをレンダリング中でも、常にフロントエンド用に解決されたHTMLを出力します。<RichText />や<InnerBlocks />などのテンプレート疑似コンポーネントは、埋め込みブロックを返す前に解決されます。

複数のスロット

$content変数を連想配列にして、bs_block関数で対応するキーを呼び出すだけで、複数のコンテンツスロットを作成できます。

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

ブロックタグ

HTMLタグ構文を使うと、任意のブロックを埋め込めます。次の2つの形式を使用できます。

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

どちらも同じブロックをレンダリングします。<bs:>構文では、ハイフンが名前空間の区切り文字に変換されます(acme-heroはacme/heroになります)。ハイフンを左から順に試し、最初に登録された候補を採用するため、ハイフンを含む名前空間も解決できます。<bs:acme-ui-button>の場合は、acme/ui-button、次にacme-ui/buttonが試されます。<block>構文では、完全なブロック名をname属性として指定します。

BlockstudioブロックとコアのWordPressブロックの両方を使用できます。Blockstudioブロックは、テンプレート、Tailwind、アセットを含む完全なパイプラインを通じてレンダリングされます。コアブロックは、組み込みのブロックレンダラーを使い、WordPressのブロックレンダリングシステムを通じてレンダリングされます。

仕組み

ブロックタグの動作は、配置場所によって異なります。

ブロックテンプレートと投稿コンテンツの場合、タグは実行時にレンダリング済みのHTMLに置き換わります。参照先ブロックの最終的なマークアップがページに直接埋め込まれます。エディター内にWordPressブロックは作成されず、純粋なレンダリング機構として機能します。

ページ、パターン、サイトテンプレートの場合、ファイルソースの同期またはWordPressへの登録前に、タグはネイティブのWordPressブロックへ変換されます。これにより、ブロックがエディターに表示され、対象が編集に対応していれば編集でき、WordPressの完全なブロックライフサイクルを経由します。タグ構文は、テンプレートファイルでブロックコンテンツを定義するための省略表記です。

この違いは重要です。テンプレート内のブロックタグは出力を生成し、ページ、パターン、サイトテンプレート内のブロックタグはネイティブブロックを生成します。

ブロックテンプレート内

ブロックタグは、TwigおよびPHPテンプレート内で自動的にレンダリングされます。設定は不要です。<bs:>構文と<block>構文のほか、登録済みのprefixタグやエイリアスタグも対象です。そのため、テンプレートからbs_render_block()を呼び出さずに直接タグを出力できます。ブロックのテンプレート出力にHTML埋め込まれた状態でレンダリングされます。

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

投稿コンテンツ内

ページレベルのレンダリング(投稿コンテンツ、ウィジェット領域)はオプトイン方式です。

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

またはフィルターを使います。

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

構文

自己終了タグ:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

内部コンテンツを持つペアタグ:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

自由に組み合わせられます。どちらの構文も互いにネストできます。

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

プレフィックスの省略形

ブロックタグでは、プロジェクト固有のプレフィックス省略形も使用できます。1つ以上の名前空間をプレフィックスに登録すると、Blockstudioが<prefix-slug>を、登録した名前空間の順に最初のブロックへ解決します。

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

上記の例では、<theme-card>はtheme-components/cardに解決され、theme-components/buttonが登録されていない場合、<theme-button>はbsui/buttonにフォールバックし、<theme-ui-feature-matrix>はtheme-components/ui-feature-matrixに解決されます。

プレフィックスは組み合わせることもできます。プレフィックス付きタグが直接解決できず、残りのスラッグ自体が登録済みのプレフィックスタグである場合、解決処理が再帰的に行われるため、ブランドプレフィックスを名前空間プレフィックスの上に重ねられます。

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

<theme-ui-input>にはtheme-components/ui-inputブロックがないため、uiプレフィックスにフォールスルーし、bsui/inputに解決されます。直接一致が常にネストした解決より優先され、許可・拒否ルールは最終的に解決されたブロックに適用されます。

blockstudio.jsonでプレフィックスを設定することもできます。

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

プレフィックスには小文字または数字を使用し、先頭は英字にしてください。ハイフンは使用できません。 blockstudio/block_tags/tag_aliasesで指定した明示的なエイリアスは、プレフィックス解決より優先されます。 不明なプレフィックス付きタグはそのまま保持されます。

プレフィックス付きタグとエイリアスタグは、引き続き記述を簡単にするために使用できます。標準かつ移植可能な表記は常に<bs:namespace-slug>です。これはプロジェクトのフィルターに依存せず、実際のブロック名を記録するためです。

HTML
<bs:theme-components-card />
<bs:bsui-input />

Blockstudioの例、生成される診断情報、プログラムによる出力では、この標準表記が使われます。古い省略表記を削除したいプロジェクトでは、WordPressを起動せずに実行できる、単独でドライランを先に行う標準タグへの移行を利用できます。

コアブロック

レンダラーが登録されているブロックであれば、どれでも使用できます。

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

または<block>構文を使います。

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

許可リストと拒否リスト

タグでレンダリングできるブロックを制御します。

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

allowは一致するパターンだけに制限します。denyは一致するパターンを除外し、優先されます。どちらもfnmatch()による*ワイルドカードをサポートします。これらは両方の構文と、テンプレートレベルおよびページレベルのレンダリングに適用されます。

フィルター: blockstudio/block_tags/allowとblockstudio/block_tags/deny。

HTMLの引き継ぎ

data-が付いた属性は、レンダリングされたブロックのルート要素に引き継がれます。html-が付いた属性も引き継がれ、プレフィックスは取り除かれます。どちらの構文でも使用できます。引き継がれた属性はルート要素の既存の値と統合されず、置き換えます。そのため、html-classはブロック独自のクラスを置き換えます。

Blockstudioブロックは、フィールドとして宣言されていないグローバル属性もルート要素に設定します。対象はid、style、role、title、lang、dir、hidden、tabindexおよびすべてのaria-*属性です。宣言済みのフィールドは常に優先されるため、titleフィールドを持つブロックには、代わりに$a['title']の値が設定されます。転送されたスタイルはsafecss_filter_attr()を通り、投稿コンテンツ内のスタイル属性にはフィルターWordPressが適用されます。また、テンプレートですでに設定されているスタイルに追加されます。

属性値はHTMLであるため、タグの解析時にエンティティは一度デコードされます。title="Tom &amp; Jerry"はテンプレートにTom & Jerryとして渡され、出力時に再びエスケープされます。引用符で囲まれた値には>を含められます。Tailwindのバリアントやアニメーションセレクターと同様に、自己終了タグとペアタグの両方で使用できます。

classを含め、ブロックが宣言していないその他の属性はHTMLに渡されません。WP_DEBUGが有効な場合、Blockstudioはリクエストごとに_doing_it_wrong()を通じて、該当する各属性を一度報告します。その属性のフィールドを宣言するか、data-、aria-、またはhtml-属性として記述してください。

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

カスタムレンダラー

追加のブロックタイプ用にカスタムブロックレンダラーを登録します。レンダラーは属性配列と内部コンテンツ文字列を受け取り、WordPressブロック配列を返します。

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

コンテナーブロックの内部コンテンツを解析して子ブロックにする必要がある場合は、同じフィルター内に2つ目の項目を追加します。

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

blockstudio/block_tags/buildersは、ブロックタグとblockstudio/parser/element_mappingで選択されたカスタムブロックの両方に適用されます。要素マッピングされたプロジェクトブロックの内部テキストをBlockstudioフィールドに移したり、カスタムブロック配列を構築したりする場合に適したフックです。

blockstudio/block_tags/renderersとblockstudio/parser/renderersは、同じレジストリとコールバック形式を受け取ります。互換性とパーサーレベルでの最終的な上書きのため、引き続き利用できます。フィルターは次の順序で実行されます。

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

後続のフィルターは、先行するフィルターで登録されたレンダラーを置き換えられます。

プログラムからの使用

PHPの任意の文字列にタグのレンダリングを適用します。

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

コンポーネント

ブロックタグはコンポーネントと相性が良い機能です。コンポーネントはプログラムからのみレンダリングされ、エディターには表示されないブロックです。

HTML
<bs:mytheme-card title="My Card" description="Card content." />

パーサー

ブロックタグは、DOMDocumentを置き換える軽量な文字列スキャナーで処理されます。パーサーは<bs:>構文と<block>構文、深さを追跡する同名タグのネスト、引用符で囲まれた属性値、再帰的なコンテナーブロックに対応しています。この用途に特化しており、DOMDocumentとWordPressのWP_HTML_Tag_Processorの両方よりベンチマークで高速です。また、名前空間プレフィックスの削除や属性名の小文字化といった、DOMDocumentの既知の問題も回避します。

ページ、パターン、サイトテンプレートでは、同じパーサーがHTMLの生要素(<p>、<div>、<h1>など)も処理し、対応するWordPressコアブロックにマッピングします。

要素マッピングが<p>を、contentリッチテキスト属性を宣言した登録済みの非コアBlockstudioブロックに割り当てている場合、内部HTMLは自動的にそのcontent属性に渡されます。これには、ブロックレベルで要素マッピングされたcodeやimgなどのインラインタグも含まれます。子要素が画像だけの段落は、<img>がマッピングするブロックになります。ネストしたブロックタグやブロックレベルのHTMLは、引き続き通常の内部ブロック解析にフォールバックします。<block name="core/shortcode">はショートコードのテキストをブロックのコンテンツとして保持します。