コンテンツへスキップ

ページとパターン

Blockstudioを使うと、WordPressページ、ブロックパターン、サイトエディターテンプレートをテーマ内のファイルとして定義できます。HTML風のテンプレートを記述すると、BlockstudioのパーサーがネイティブのWordPressブロックに変換します。

  • ページはWordPress投稿としてデータベースに同期され、ファイルテンプレートとページコンテンツが同期された状態に保たれます。
  • パターンはregister_block_pattern()を通じてメモリ上に登録され、ブロック挿入ツールからユーザーが任意の場所に配置できます。
  • サイトテンプレートはファイルベースのwp_templateとwp_template_partソースをWordPressサイトエディターに提供します。

3つの機能はすべて、同じHTMLパーサーとブロック構文を共有します。

ファイルベースのページを作成する

ファイルベースのページテンプレート、同期、ロックの実践的な解説です。

フォルダー構成

コード
theme/
├── pages/
│   ├── about/
│   │   ├── page.json
│   │   └── index.php
│   └── contact/
│       ├── page.json
│       └── index.twig
├── patterns/
    ├── hero/
    │   ├── pattern.json
    │   └── index.php
    └── cta/
        ├── pattern.json
        └── index.blade.php
├── templates/
    └── front-page/
        ├── template.json
        └── index.php
└── parts/
    └── header/
        ├── part.json
        └── index.php

各サブフォルダーにはJSON設定ファイル(page.json、pattern.json、template.json、またはpart.json)とテンプレートファイルが含まれます。

テンプレートエンジン

テンプレートはindex.phpのプレーンなマークアップ、またはTwigやBladeで記述できます。

ファイル エンジン 要件
index.php なし(そのまま読み込み、PHPコードは実行されません) なし
index.twig Twig Timber
index.blade.php Blade illuminate/view

テンプレートファイルが複数ある場合の優先順位は、index.php > index.blade.php > index.twigです。

テンプレートはリクエストコンテキストが設定される前の初期化時にコンパイルされるため、TwigとBladeのテンプレートから動的変数にはアクセスできません。{{ "text"|upper }}や{{ strtoupper("text") }}などの組み込み関数やフィルターに便利です。

HTMLからブロックへのマッピング

標準のHTML要素は対応するWordPressブロックに自動変換されます。

テキスト

HTML ブロック
<p> core/paragraph
<h1> – <h6> core/heading
<ul> core/list(順序なし)
<ol> core/list(順序あり)
<li> core/list-item
<blockquote> core/quote
<code> core/code
<pre> core/preformatted

リストの構造は維持されます。<li>内の<ul>または<ol>は、そのcore/list-itemの内側にあるcore/listブロックとなります。これはエディターで保存される形式であり、リストは任意の深さまでネストできます。リストまたは項目に指定したclassは、そのclassNameになります。これにより、ページファイルからis-style-checksなどのブロックスタイルを設定できます。<block name="core/list" className="...">も同様に機能します。

メディア

HTML ブロック
<img> core/image
<figure> core/image(キャプション付き)
<audio> core/audio
<video> core/video

レイアウト

HTML ブロック
<div>、<section> core/group
<main>、<header>、<footer>、<article>、<aside> 要素をtagNameとして保持するcore/group
<hr> core/separator
<details> core/details
<table> core/table

ブロック構文

直接対応するHTML要素がないブロックには、<block>要素を使用します。

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1>Welcome</h1>
  <p>Content inside the cover block.</p>
</block>

コアブロック

HTML
<!-- Pullquote -->
<block name="core/pullquote">
  <p>An important quote.</p>
</block>

<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>

<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
  <h2>Cover Title</h2>
</block>

<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />

<!-- Spacer -->
<block name="core/spacer" height="50px" />

<!-- Gallery -->
<block name="core/gallery">
  <img src="https://example.com/1.jpg" alt="Image 1" />
  <img src="https://example.com/2.jpg" alt="Image 2" />
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <h3>Column 1</h3>
  </block>
  <block name="core/column">
    <h3>Column 2</h3>
  </block>
</block>

<!-- Buttons -->
<block name="core/buttons">
  <block name="core/button" url="/get-started">Get Started</block>
</block>

<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Item 1</p>
  <p>Item 2</p>
</block>

カスタムブロック

登録済みの任意のブロックに同じ構文を使用できます。

HTML
<block name="blockstudio/section">
  <h1>Welcome</h1>
</block>

<block name="acf/hero" title="Hero Title" background="dark">
  <p>Inner content becomes InnerBlocks.</p>
</block>

属性

HTML 要素の<block>属性は、ブロック属性として渡されます。次のJSON値がサポートされています:

HTML
<block name="core/heading" level="3">Custom Heading</block>

<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked content.</p>
</block>

<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />

属性値は、ブラウザーが読み取る方法と同じように一度デコードされるため、data-animate="[&amp;>span]:fade"とdata-animate="[&>span]:fade"には同じ値が格納されます。

Blockstudioブロックにマッピングされた要素では、すべての属性がブロックとともに保存されます。宣言済みのフィールドはテンプレートに渡されます。ブロックで宣言されていないグローバル属性(id、style、role、title、lang、dir、hidden、tabindex、aria-*、data-*)は、ブロックタグと同様に、レンダリング時にブロックのルート要素に設定されます。ページやパターンのソースでは、html-プレフィックスはこれらのグローバル属性のいずれかを指定するだけなので、html-role="note"はroleとして出力されます。一方、html-onclickなどのイベントハンドラーは出力されません。宣言されていないclassを含むそれ以外のすべての属性は、ページに渡されず、投稿コンテンツに残ります。また、wp bs pages syncは解析するすべてのページについてその旨を報告します。

カスタムブロックレンダラー

HTMLパーサーはレジストリベースのアーキテクチャを採用しています。blockstudio/block_tags/buildersを使ってカスタムブロックのビルダーを追加します:

PHP
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
    $builders['acf/hero'] = function( array $attrs, string $inner_content ) {
        $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );

        return array(
            'blockName'    => 'acf/hero',
            'attrs'        => $attrs,
            'innerBlocks'  => $inner_blocks,
            'innerHTML'    => '',
            'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
        );
    };

    return $builders;
}, 10, 2 );

次に、任意のテンプレートで使用します:

HTML
<block name="acf/hero" background="dark">
  <h1>Welcome</h1>
</block>

コアブロックのレンダリング方法を上書きすることもできます:

PHP
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
    $renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
        $content = trim( $inner_content );
        $attrs['align'] = $attrs['align'] ?? 'center';

        return array(
            'blockName'    => 'core/paragraph',
            'attrs'        => $attrs,
            'innerBlocks'  => array(),
            'innerHTML'    => '<p class="has-text-align-center">' . $content . '</p>',
            'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
        );
    };

    return $renderers;
}, 10, 2 );

ビルダーコールバックには、解析済みの属性と生の内部コンテンツが渡されます。戻り値はWordPressブロック配列である必要があります。フィルターの完全な順序とコンテナーの例については、カスタムレンダラーを参照してください。

ビルダー関数のシグネチャ

PHP
/**
 * @param array  $attrs         Parsed element or block-tag attributes.
 * @param string $inner_content Raw inner content.
 * @return array WordPress block array.
 */
function my_builder( array $attrs, string $inner_content ): array {}

要素のマッピング

デフォルトでは、<h1>、<p>、<img>などの標準HTML要素は、コアWordPressブロックにマッピングされます。blockstudio/parser/element_mappingフィルターを使うと、このマッピングを上書きし、任意のHTML要素を別のブロックに割り当てられます:

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['h1'] = 'custom/heading';
    $mapping['h2'] = 'custom/heading';
    $mapping['p']  = 'custom/paragraph';
    $mapping['img'] = 'custom/image';

    return $mapping;
}, 10, 2 );

このフィルターが有効な場合、テンプレート内のすべての<h1>はcore/headingの代わりにcustom/headingブロックを生成します。要素の属性は対象ブロックに渡されます。対象ブロック名にレンダラーが登録されていれば、それが使用されます。登録されていなければ、汎用ブロック構造が作成されます。

テーマやプラグインが、すべてのページテンプレートとパターンテンプレートでデフォルトを置き換えるカスタムブロックタイプを提供している場合に便利です。

単純な<p>マッピングでは、Blockstudioにより、内部のHTMLを登録済みの非コアBlockstudioブロックのcontentリッチテキスト属性に直接渡せます。対象ブロックは、id: "content"とtype: "richtext"を持つ属性を宣言している必要があります。 インライン書式(a、b、br、code、del、em、i、img、ins、mark、s、small、span、strong、sub、sup、u)は、同じタグが要素にマッピングされていても、渡される値にそのまま残ります。デフォルトではcodeとimgが該当します。子要素が画像だけの段落は、単独の画像に対してMarkdownが生成するものと同じ、<img>のマッピング先ブロックになります。ネストされたブロックタグとブロックレベルのHTMLは、引き続き内部ブロックとして解析されます。

対象ブロックが要素の属性に依存する場合、マッピング値には呼び出し可能な値も指定できます:

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['div'] = function( array $attrs ) {
        if ( isset( $attrs['width'] ) ) {
            return 'theme/row';
        }

        if ( isset( $attrs['gap'] ) ) {
            return 'theme/flow';
        }

        return 'theme/div';
    };

    return $mapping;
} );

<section>や<div>などのコンテナー要素からマッピングされたカスタムブロックは、ネストされたHTMLの子要素を再帰的に解析します。そのため、内部の見出し、画像、ブロックタグ、段落はネイティブな子ブロックになります。

完全な例

複数のブロックタイプを組み合わせたページテンプレートの全例:

HTML
<div>
  <h1>Welcome to Our Site</h1>
  <p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>

  <block name="core/columns">
    <block name="core/column">
      <h3>Feature One</h3>
      <p>First feature description.</p>
    </block>
    <block name="core/column">
      <h3>Feature Two</h3>
      <p>Second feature description.</p>
    </block>
  </block>

  <block name="core/cover" url="https://example.com/hero.jpg">
    <h2>Our Mission</h2>
    <p>Building amazing things together.</p>
  </block>

  <details>
    <summary>FAQ</summary>
    <p>Answers to common questions.</p>
  </details>

  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
    <block name="core/button" url="/learn-more">Learn More</block>
  </block>
</div>