コンテンツへスキップ

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

従来のWordPressページ作成はブロックエディター内で行います。ブロックをドラッグし、設定を調整して、保存をクリックします。クライアントが自分でページを作るには便利ですが、開発者が構造化され、バージョン管理されたページを作るには問題があります。ページのレイアウトはコードではなくデータベースに保存されるため、プルリクエストで確認したり、gitで以前の状態に戻したり、新規インストールで再現したりできません。

Blockstudioのファイルベースページなら、この問題を解決できます。テーマ内のファイルとしてページを定義し、HTMLテンプレートを記述してWordPressブロックに変換し、クライアントが編集できる部分とできない部分を正確に制御できます。明示的なコマンドでファイルを通常のWordPress投稿に同期し、テンプレートを信頼できる唯一の情報源として保ちます。

このガイドでは、ページを一から作る方法を、ファイルベースのページをクライアント案件で実用的にするロックと編集の制御を中心に解説します。

最初のページ

テーマにpagesフォルダーを作成し、その中にサブフォルダーと2つのファイルを追加します。

コード
theme/
└── pages/
    └── about/
        ├── page.json
        └── index.php
JSON
{
  "name": "about",
  "title": "About Us",
  "postStatus": "publish"
}
HTML
<h1>About Us</h1>
<p>We build things for the web.</p>

ページの同期コマンドを実行します。

シェル
wp bs pages sync

BlockstudioはHTMLをWordPressブロックに解析し、スラッグaboutの「About Us」というページを作成します。エディターで開くと、手動で追加した場合と同じように見出しと段落が表示されます。

index.phpを編集してテキストを変更し、コマンドをもう一度実行します。エディターを再読み込みすると変更が反映されています。HTMLを書き、意図的に同期してブロックを作る、これが基本の流れです。

テンプレート言語

BlockstudioのHTMLパーサーは、標準のHTML要素をWordPressブロックに変換します。<p>を書くと段落ブロックになり、<h2>を書くと見出しブロックになります。対応は直感的です。

HTML ブロック
<p> 段落
<h1>〜<h6> 見出し(タグに対応するレベル)
<ul>、<ol> リスト
<blockquote> 引用
<img> 画像
<div>、<section> グループ
<hr> 区切り線
<details> 詳細
<table> テーブル

直接対応するHTML要素がないブロックには、name属性を指定した<block>要素を使います。

HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h2>Hero Title</h2>
  <p>Content over the background image.</p>
</block>

<block name="core/spacer" height="80px" />

<block name="core/buttons">
  <block name="core/button" url="/contact">Get in Touch</block>
  <block name="core/button" url="/work">See Our Work</block>
</block>

<block>要素の属性はブロック属性として渡されます。値は自動的に変換され、"true"はブール値、"3"は整数になり、'{"type":"flex"}'のようなJSON文字列はオブジェクトにデコードされます。

レイアウト

グループでは、layout属性を使って複数のレイアウトモードを指定できます。

HTML
<!-- Default group (stacked) -->
<div>
  <p>Stacked by default.</p>
</div>

<!-- Row (horizontal flex) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
  <p>Side</p>
  <p>by side</p>
</block>

<!-- Stack (vertical flex) -->
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
  <p>Stacked</p>
  <p>with flex</p>
</block>

<!-- Columns -->
<block name="core/columns">
  <block name="core/column">
    <p>Left column.</p>
  </block>
  <block name="core/column">
    <p>Right column.</p>
  </block>
</block>

カスタムブロック

<block>構文は、独自のBlockstudioブロックを含め、登録済みのあらゆるブロックで使えます。

HTML
<block name="my-theme/hero" title="Welcome" background="dark" />
<block name="my-theme/testimonial" quote="Great product." author="Jane" />

属性はブロックのBlockstudioフィールド値に自動的に割り当てられます。

ランディングページを作成する

構造とレイアウトにコアブロックを使った、完成したランディングページの例です。

JSON
{
  "name": "landing",
  "title": "Landing Page",
  "slug": "landing",
  "postStatus": "publish",
  "templateLock": "all"
}
HTML
<block name="core/cover" url="https://images.unsplash.com/photo-1497366216548-37526070297c?w=1600">
  <h1>Build faster with Blockstudio</h1>
  <p>File-based blocks. Zero build step. Full editor integration.</p>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Get Started</block>
    <block name="core/button" url="/docs">Documentation</block>
  </block>
</block>

<div>
  <h2>Why developers love it</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3>No build step</h3>
      <p>Write PHP, CSS, and JavaScript. No webpack, no bundler, no transpiler.</p>
    </block>
    <block name="core/column">
      <h3>File-based</h3>
      <p>Every block is a folder. Every page is a template. Version control everything.</p>
    </block>
    <block name="core/column">
      <h3>Full editor support</h3>
      <p>Fields, previews, and InnerBlocks work in the block editor out of the box.</p>
    </block>
  </block>
</div>

<block name="core/media-text" mediaurl="https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=800" mediatype="image">
  <h2>Ship entire sites from your IDE</h2>
  <p>Define pages, blocks, and patterns as files. Blockstudio handles the rest.</p>
</block>

<div>
  <h2>Frequently asked questions</h2>
  <details>
    <summary>Do I need to learn React?</summary>
    <p>No. Templates are PHP. Fields are JSON. Interactivity is optional.</p>
  </details>
  <details>
    <summary>Does it work with my existing theme?</summary>
    <p>Yes. Drop a blockstudio folder into any theme and start creating blocks.</p>
  </details>
</div>

<div>
  <block name="core/buttons">
    <block name="core/button" url="/get-started">Start Building</block>
  </block>
</div>

このページは、カバーヒーロー、3列の特徴グリッド、メディアとテキストのセクション、FAQアコーディオン、CTAで構成されています。すべて1つのHTMLファイルにあります。page.json内のtemplateLock: "all"により、クライアントは何も変更できません。次のセクションでは、制限を緩める方法を説明します。

エディターを制御する

ファイルベースのページが真価を発揮するのはここです。Blockstudioには独立した制御が2つあります。テンプレートロックとブロック編集モードです。これらを組み合わせると、クライアントがページのどの部分を変更できるか正確に指定できます。構造をロックしながらテキストの編集を許可したり、一部のセクションを固定して残りを自由に編集できるようにしたりできます。クライアントが特定の3つの見出しにだけ入力できるページも作れます。

テンプレートロック

page.json内のtemplateLockプロパティは、ブロックの追加、削除、並べ替えができるかどうかなど、構造の編集を制御します。

"all"(初期設定)

JSON
{
  "name": "terms",
  "templateLock": "all"
}

最も厳しいロックです。クライアントはブロックの追加、削除、移動ができません。blockEditingModeと組み合わせない限り、ブロックの内容も編集できません。値を指定しない場合の初期設定です。

使用例: 法的情報、利用規約、プライバシーポリシーなど、コードを通じてのみ内容を変更するページ。

"insert"

JSON
{
  "name": "about",
  "templateLock": "insert"
}

クライアントはブロックの追加や削除はできませんが、既存のブロックを移動し、内容を編集できます。ブロック数は固定されますが、順序は変更できます。

使用例: セクションの構成は固定しつつ、クライアントが順序を変更できるページ。セクション数があらかじめ決まっていて、順序はクライアントが選べるポートフォリオページなど。

"contentOnly"

JSON
{
  "name": "homepage",
  "templateLock": "contentOnly"
}

クライアントはテキストを編集できますが、ブロックの追加、削除、移動はできません。"all"との違いは、"all"では内容の編集も禁止されるのに対し、"contentOnly"では編集が明示的に許可される点です。

使用例: クライアント向けページで最も一般的な選択肢です。開発者がレイアウトを管理し、クライアントがテキストを入力します。

false

JSON
{
  "name": "blog",
  "templateLock": false
}

ロックはありません。クライアントはブロックの追加、削除、移動、編集を自由に行えます。テンプレートは最初の構成を提供しますが、その後はクライアントが自由に編集できます。

使用例: ブログのインデックスページ、自由形式のコンテンツページなど、クライアントに編集の自由をすべて委ねるページ。

ブロック編集モード

templateLockが構造(追加、削除、移動)を制御するのに対し、blockEditingModeは個々のブロックの操作を制御します。ブロックを選択、設定、編集できるかどうかを指定します。

page.jsonでページの初期設定を指定します。

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

"default"

完全編集モードです。ブロックを選択し、設定を変更して、内容を編集できます。通常のエディター操作です。

"contentOnly"

ブロックは編集できますが、編集できるのはテキスト内容だけです。ブロック設定を開いたり、色を変更したり、余白を調整したり、コンテンツ以外の属性を変更したりすることはできません。ブロックツールバーに表示されるのはテキスト書式のオプションだけです。

"disabled"

ブロックは完全に操作できません。エディターには表示されますが、クリック、選択、変更は一切できません。クライアントはコンテンツを見られますが、操作することはできません。

要素ごとのオーバーライド

ここからが興味深いところです。ページレベルのblockEditingModeはページ上のすべてのブロックに既定値を設定しますが、テンプレートでは個々の要素ごとに上書きできます。

JSON
{
  "name": "landing",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Edit This Heading</h1>
  <p blockEditingMode="contentOnly">Edit this paragraph too.</p>
</block>

<div>
  <h2>Features</h2>
  <p>This paragraph cannot be edited (inherits "disabled").</p>
  <p blockEditingMode="contentOnly">But this one can.</p>
</div>

<block name="core/buttons">
  <block name="core/button" url="/contact">This button is frozen</block>
</block>

ページの既定値は"disabled"なので、すべてのブロックは操作できない状態で始まります。次に、特定の要素で"contentOnly"を有効にすると、そのテキストだけが編集可能になります。その結果、クライアントが入力できるのは、ヒーロー見出しと段落の2つのテキストフィールド、および1つの機能紹介段落だけです。それ以外はすべてロックされます。

これはあらゆるHTML要素(<h1>、<p>、<div>など)と<block>要素で機能します。特定の要素にblockEditingMode="default"を設定して、完全な編集権限を与えることもできます。

HTML
<block name="core/buttons" blockEditingMode="default">
  <block name="core/button" url="/contact">Fully editable button</block>
</block>

これでクライアントはボタンのテキスト、URL、スタイル、その他すべての設定を変更できます。ページ上のそれ以外の部分は固定されたままです。

祖先へのカスケード

要素ごとのオーバーライドがコンテナブロックにどう作用するかについて、重要な点があります。ページの既定値が"disabled"で、グループ内の見出しにblockEditingMode="contentOnly"を設定した場合、その見出しにアクセスできる必要があります。しかし、親グループは"disabled"なので、そもそも中に入ることができません。

Blockstudioがこれを自動的に処理します。子ブロックに編集モードのオーバーライドがあると、その子にアクセスできるよう、すべての祖先ブロックが"contentOnly"に設定されます。親コンテナのモードを手動で設定する必要はありません。編集可能にしたいブロックにオーバーライドを設定するだけで、そこまでの経路が開きます。

HTML
<!-- page default: "disabled" -->
<div>
  <!-- this group is auto-set to "contentOnly" because it contains an override -->
  <div>
    <!-- this group is also auto-set to "contentOnly" -->
    <p blockEditingMode="contentOnly">Deeply nested but still editable.</p>
  </div>
</div>

祖先へのカスケードで引き上げられるコンテナは"contentOnly"までで、"default"にはなりません。つまり、祖先グループには移動できるようになりますが(中に入れます)、完全な編集はできません(設定を変更できません)。

設定の組み合わせ

templateLockとblockEditingModeを組み合わせることで、制御の度合いを調整できます。特に便利な組み合わせを紹介します。

開発者がすべてを管理する

JSON
{ "templateLock": "all" }

blockEditingModeは不要です。既定のtemplateLock: "all"がすべての変更を禁止します。コードだけで管理するページに使います。

クライアントがすべてのテキストを編集する

JSON
{ "templateLock": "contentOnly" }

クライアントはどのブロックのテキストも編集できますが、ページ構造は変更できません。シンプルで自由度の高い設定です。

クライアントが特定のテキストだけを編集する

JSON
{
  "templateLock": "all",
  "blockEditingMode": "disabled"
}

テンプレート内の特定の要素にblockEditingMode="contentOnly"を組み合わせます。最もきめ細かな設定で、クライアントが編集できるのは指定したブロックだけです。

クライアントが固定セクションの順序を変更する

JSON
{ "templateLock": "insert" }

クライアントはセクションの並べ替えとコンテンツの編集ができますが、ブロックの追加や削除はできません。セクションが固定されていて、順序だけを変更できるページに適しています。

クライアントに完全な権限を与える

JSON
{ "templateLock": false }

テンプレートは出発点です。その後はクライアントが自由に操作できます。

クライアントの編集内容を保持する

既定では、テンプレートファイルを更新すると、Blockstudioがページ全体のコンテンツを置き換えます。クライアントがエディターで見出しを編集していても、次回の同期後にはその編集内容が失われます。開発者が管理するページなら問題ありませんが、クライアントがコンテンツを作成するページでは、編集内容を保持する方法が必要です。

キー

要素にkey属性を追加すると、置き換えではなくマージの対象になります。

HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1>Default Hero Title</h1>
  <p>Default hero description.</p>
</block>

<div key="features">
  <h2>Features</h2>
  <p>Feature introduction text.</p>
</div>

<div>
  <h2>Unkeyed Section</h2>
  <p>This gets replaced on every sync.</p>
</div>

テンプレートが変更され、ページが再同期されると、次のようになります。

  • キー付きブロックは、クライアントのコンテンツ(テキスト、内部ブロック、書式)を保持します。カバーのurlなど、テンプレートの構造属性は更新されます。
  • キーなしブロックは、テンプレートのバージョンに完全に置き換えられます。

キーはブロック全体とそのすべての子要素を保護します。キー付きグループ内の段落ごとにキーを付ける必要はありません。グループのキーが内部のすべてを保護します。

キーは一意である必要がある

キーはテンプレート全体で一意である必要があります。2つの要素が同じキーを持つ場合、2つ目はキーなしとして扱われ、PHP警告が出力されます。"hero"、"features"、"cta"、"testimonial-section"のように、内容が分かる名前を使ってください。

テンプレートを発展させる

キーを使うと、既存のクライアントコンテンツに影響を与えずにテンプレートへ新しいセクションを追加できます。

HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
HTML
<h1 key="title">Welcome</h1>
<div key="services">
  <h2>Our Services</h2>
  <p>We do great work.</p>
</div>
<div key="testimonials">
  <h2>What Clients Say</h2>
  <p>Default testimonial text.</p>
</div>

同期時に、タイトルとサービスの編集内容はクライアントのものが保持されます。新しいお客様の声セクションは、テンプレートの既定のコンテンツとともに表示されます。後からテンプレートからキー付きブロックを削除すると、ページからも削除されます。

クライアントのワークフロー全体

実際のプロジェクトでの流れをまとめます。

JSON
{
  "name": "homepage",
  "title": "Home",
  "slug": "home",
  "postStatus": "publish",
  "templateLock": "all",
  "blockEditingMode": "disabled"
}
HTML
<block name="core/cover" key="hero" url="https://example.com/hero.jpg">
  <h1 blockEditingMode="contentOnly">Your Company Name</h1>
  <p blockEditingMode="contentOnly">Your tagline goes here.</p>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Contact Us</block>
  </block>
</block>

<div key="features">
  <h2 blockEditingMode="contentOnly">What We Do</h2>
  <block name="core/columns">
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service One</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Two</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
    <block name="core/column">
      <h3 blockEditingMode="contentOnly">Service Three</h3>
      <p blockEditingMode="contentOnly">Describe this service.</p>
    </block>
  </block>
</div>

<block name="core/media-text" key="about" mediaurl="https://example.com/team.jpg" mediatype="image">
  <h2 blockEditingMode="contentOnly">About Us</h2>
  <p blockEditingMode="contentOnly">Tell your story here.</p>
</block>

<div key="cta">
  <h2 blockEditingMode="contentOnly">Ready to get started?</h2>
  <block name="core/buttons">
    <block name="core/button" url="/contact">Get in Touch</block>
  </block>
</div>

このページにはキー付きセクションが4つあります。クライアントはblockEditingMode="contentOnly"が付いた見出しや段落を編集でき、その編集内容はテンプレートの更新後も保持されます。レイアウト、画像、ボタンのURL、全体構造は開発者が管理します。後から開発者が「about」と「cta」の間にお客様の声セクションを追加すると、次回の同期時に、クライアントのテキストを変更せずに反映されます。

ブロックバインディング:キーに代わる方法

WordPress 6.5で導入されたブロックバインディングAPIは、ブロック属性を投稿メタデータに接続します。キーで保護されるブロックのマークアップ内に編集可能なコンテンツを保存する代わりに、テンプレート同期の影響を受けないwp_postmetaにコンテンツを保存します。

HTML
<h1 metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'>
  Default Title
</h1>

<p metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'>
  Default description.
</p>

メタキーはPHPに登録する必要があります。

PHP
register_post_meta( 'page', 'hero_title', array(
    'show_in_rest' => true,
    'single'       => true,
    'type'         => 'string',
    'default'      => 'Default Title',
) );

ブロックバインディングには、キーより優れた点が2つあります。meta_query経由でWP_Queryを使ってデータをクエリできることと、REST APIで利用できることです。一方で、PHPに各メタキーを登録する必要があり、バインディングは個々のブロック属性でのみ機能します(複雑なネスト構造のコンテンツには使えません)。

ブロック構造が重要なリッチコンテンツのセクション(見出し、段落、画像を含むグループなど)にはキーを使います。クエリしたり、別の場所に表示したりする必要がある個々のテキスト値にはバインディングを使います。

投稿タイプテンプレート

templateForを使うと、特定の種類の新しい投稿すべてに既定のブロック構造を設定できます。

JSON
{
  "name": "product-template",
  "title": "Product Template",
  "templateFor": "product",
  "templateLock": "insert"
}
HTML
<h1>Product Name</h1>

<block name="core/columns">
  <block name="core/column">
    <img src="" alt="Product image" />
  </block>
  <block name="core/column">
    <p>Product description goes here.</p>
    <block name="core/buttons">
      <block name="core/button" url="#">Buy Now</block>
    </block>
  </block>
</block>

<div>
  <h2>Specifications</h2>
  <table>
    <thead>
      <tr><th>Feature</th><th>Value</th></tr>
    </thead>
    <tbody>
      <tr><td>Weight</td><td>1.2 kg</td></tr>
    </tbody>
  </table>
</div>

新しい「product」投稿はすべて、この構造から始まります。templateLock: "insert"を設定すると、編集者はセクションの並べ替えとコンテンツの編集ができますが、ブロックの追加や削除はできません。

ヒント

意図したデプロイ時点で同期する。 ページソースを変更またはデプロイした後にwp bs pages syncを実行します。フロントエンドや管理画面へのアクセスではページは同期されません。PHPデプロイツールからBlockstudio\Pages::reconcile()を呼び出し、機械可読なレポートを確認できます。

重要な投稿IDを固定する。 メニュー、ハードコードされたリンク、外部システムから参照されるページには、page.jsonでpostIdを使います。固定しない場合、ページを削除して再作成すると新しいIDが割り当てられ、参照が切れてしまいます。

sync: falseをひな形に使う。 ページを一度作成した後、完全にクライアントへ引き渡す場合は、"sync": falseを設定してBlockstudio\Pages::force_sync()で作成します。通常の調整処理では無視されます。

PHPでロックと解除を行う。Blockstudio\Pages::lock('about')を呼び出すと、特定のページの同期を停止できます(クライアントの編集作業期間に便利です)。Blockstudio\Pages::unlock('about')を呼び出すと、同期が再び有効になります。

テンプレートエンジン。 PHPのほか、Twig(Timberが必要)やBlade(illuminate/viewが必要)でもテンプレートを記述できます。ループやフィルターに便利ですが、ページテンプレートがコンパイルされるのは明示的な同期時であり、フロントエンドのリクエスト時ではありません。ソースのコンパイル自体にPHP専用のヘルパーが必要な場合は、PHPを使ってください。

強制同期ではキーは無視される。Pages::force_sync('about')を呼び出すと、キーと更新時刻のチェックを無視してページ全体のコンテンツが置き換えられます。ページを意図的にテンプレートの状態に戻す場合に使います。

次のステップ

  • ページリファレンス:すべてのpage.jsonプロパティ、PHP API、キーを使ったマージ処理について詳しく説明します。
  • ページとパターンの概要:HTMLパーサー、ブロック構文のリファレンス、カスタムレンダラー、要素のマッピングを紹介します。
  • パターン:ページではなく再利用可能なブロックパターンに、同じテンプレート構文を使う方法を紹介します。