コンテンツへスキップ

アイランド

ブロックアイランドでは、通常のBlockstudioレンダリングパイプラインを維持しながら、リクエスト固有の出力を初回のHTMLレスポンスから切り離せます。

ページを積極的にキャッシュしたい一方で、あるブロックは現在の訪問者、セッション、カート、権限、またはその他の進行中のリクエストコンテキストに依存する場合に便利です。

Blockstudioブロックは引き続き動的なWordPressブロックです。アイランドによって、事前コンパイル済みの静的なHTMLになるわけではありません。代わりに、Blockstudioは初回リクエスト時のレンダリング内容を変更します:

  • ハイドレーション済みアイランドは、通常のキャッシュ安全なHTMLをレンダリングし、マウントイベントを受け取ります
  • 動的アイランドは、まずキャッシュ安全なプレースホルダーをレンダリングし、その後、訪問者のブラウザーから実際のフラグメントを取得します

モード

ハイドレーション済みアイランド

サーバー出力を安全にキャッシュでき、ブロックにフロントエンドのマウントシグナルだけが必要な場合は、ハイドレーション済みアイランドを使用します。

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

ブロックのHTML全体が初回レスポンスに含まれます。アイランドランタイムはそれを取得するためのRESTリクエストを行いません。マーカー上でblockstudio:island:hydrateを発行し、フロントエンドコードが動作を追加できるようにします。

動的アイランド

実際のブロック出力を訪問者のリクエストコンテキストでレンダリングする必要がある場合は、動的アイランドを使用します。

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

初回レスポンスにはプレースホルダーのみが含まれます。ブラウザーは準備ができた動的アイランドを1つのリクエストにまとめ、次の宛先に送信します:

Text
POST /wp-json/blockstudio/v1/island/render

このエンドポイントは、登録済みのBlockstudioブロックのうち、動的でblockstudio.island.modeがdynamicに設定されているものだけをレンダリングします。

設定

islandの値には、短縮形式またはオブジェクト形式を使用できます。

JSON
{
  "blockstudio": {
    "island": true
  }
}

trueと"hydrate"はどちらもハイドレーション済みを意味します。"dynamic"は動的を意味します。

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
プロパティ 型 デフォルト 説明
mode "hydrate"または"dynamic" "hydrate" アイランドモード。
tag string "div" マーカーのラッパータグ。
attributes string[] すべてのブロック属性 動的フラグメントリクエストに送信する属性の許可リスト。
placeholder string 自動検出 相対プレースホルダーテンプレートのパス。
loading "eager"または"visible" "eager" ランタイムが動的アイランドを取得するタイミング。
event string 未設定 動的アイランドを更新するウィンドウイベント名。
context boolean false 動的フラグメント用に、クエリー対象ページの投稿IDと投稿タイプに署名を付けて復元します。
cache booleanまたはobject false 任意のフラグメントキャッシュポリシー。

ページコンテキスト

通常、動的フラグメントはページのシェルとは独立してレンダリングされます。ブロックがページ固有の設定や関連コンテンツを読み取る場合は、ページの識別情報を利用してください。

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "context": true,
      "cache": { "ttl": 60, "per": "global" }
    }
  }
}

マーカーには、クエリー対象ページのpostIdとpostTypeがdata-bs-island-contextに含まれます。両方の値には、提供元サイトの秘密鍵を使ってブロック名と許可リスト内の属性が署名されます。署名が無効になるため、リクエスト内で変更したり追加したりすることはできません。ランタイムは、表示時やイベントによる更新も含め、既存のバッチ処理によるフラグメントリクエストとともにこれらの値を送信します。bs_render_block()、bs_block()、ブロックタグでも機能します。

フラグメントのレンダリング中、$block['postId']、$block['postType']、get_the_ID()、get_queried_object_id()はそのページを参照します。レンダリング例外の発生後も含め、処理後にWordPressクエリーと投稿のグローバル変数が復元されます。これはクエリー対象ページを指し、Query Loop内の項目ではありません。任意のURLパラメーターを再現したり、元のリクエストのURLを復元したりすることはありません。HTMLページの正規のURLが必要な場合は、get_permalink($block['postId'])を使ってください。アーカイブやクエリー対象の投稿がないレンダリングでは、ページの識別情報は送信されません。

エンドポイントは、フラグメントキャッシュを参照する前に、ページが引き続き存在すること、署名された投稿タイプであること、現在の訪問者が読み取り可能であることを確認します。有効な署名があっても、非公開投稿やパスワード保護、アイランドの適格性、属性の許可リスト、ブロック独自の権限チェックは回避できません。ページの識別情報がある場合は常にフラグメントキャッシュキーの一部となるため、異なるページにある同じブロックと属性でフラグメントが共有されることはありません。出力が訪問者にも依存する場合は、per: "user"を使うか、フラグメントキャッシュを使わないでください。

contextが省略されている場合やfalseの場合は、既存のマーカーとコンテキストに依存しない動作は変わりません。公開マーカーに機密データを含めないでください。

動的プレースホルダー

動的アイランドでは、共有フルページキャッシュで安全に使えるプレースホルダーをレンダリングしてください。プレースホルダーの分岐には訪問者固有のデータを含めないでください。

Blockstudioは次の順序でプレースホルダーを探します:

  1. 明示的に指定されたisland.placeholderパス
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. プレースホルダーフラグを指定した通常のテンプレート
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

プレースホルダーファイルがない場合は、通常のテンプレートでテンプレートフラグを使用します:

PHP
<?php if ( $isIslandPlaceholder ) : ?>
  <div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
  <div class="cart-count">
    <?php echo esc_html( acme_cart_count() ); ?>
  </div>
<?php endif; ?>

同じ値はPHP、Twig、Bladeのテンプレートでも利用できます。

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhaseは"normal"、"hydrate"、"placeholder"、または"fragment"です。

実行時の動作

Blockstudioは、レンダリングされたページにアイランドマーカーが含まれる場合にのみ、アイランドランタイムを挿入します。アイランドを含まないページでは、追加のアイランドJavaScriptは送信されません。

動的アイランドの場合、ランタイムは次の処理を行います。

  1. 準備完了したマーカーをすべて収集する
  2. ブロック名、属性、シグネチャの同一ペアを重複排除する
  3. 1つにまとめたRESTリクエストを送信する
  4. 各プレースホルダーを返されたフラグメントに置き換える
  5. blockstudio:island:renderedをディスパッチする
  6. blockstudio:island:hydrateをディスパッチする

loading: "eager"アイランドはランタイムの起動と同時にレンダリングされます。loading: "visible"アイランドはIntersectionObserverまで待機します。複数の表示中のアイランドが同時にビューポートに入ると、1つのリクエストにまとめられます。

eventは、指定したウィンドウイベントが発生するとアイランドを更新します。

JavaScript
window.dispatchEvent(new Event('cart:updated'));

失敗した場合はプレースホルダーがそのまま残り、blockstudio:island:errorがディスパッチされます。

フラグメントエンドポイント

アイランドエンドポイントは公開されていますが、汎用のブロックレンダリングAPIではありません。

各マーカーには次の情報が含まれます。

  • ブロック名
  • 許可リストに登録された属性
  • サーバーで生成されたシグネチャ

エンドポイントでレンダリングされるのは、次の条件を満たす場合のみです。

  • ブロックが登録済みである
  • ブロックが動的なWordPressブロックである
  • ブロックが動的なBlockstudioアイランドとしてマークされている
  • 受信した属性がブロックのスキーマとアイランドの許可リストを通過する
  • シグネチャが正規化されたブロック名と属性に一致する

シグネチャは、提供元のWordPressサイトでレンダリング時に、そのサイトのソルトとアイランドのペイロードから生成されます。エクスポートされたり、テーマに組み込まれたりすることはありません。

エンドポイントのレスポンスにはキャッシュ不可の印が付けられます。フラグメントをキャッシュする場合は、island.cacheを使用してください。

フラグメントのキャッシュ

動的フラグメントはデフォルトでキャッシュされません。

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

trueは短時間のグローバルキャッシュを使用します。明示的に制御するには、オブジェクト形式を使用してください。

JSON
{
  "cache": {
    "ttl": 120,
    "per": "user"
  }
}

per: "global"は、同じブロック、属性、オプトインされたページコンテキストに対して、キャッシュされたフラグメントを1つ共有します。 per: "user"は、現在のWordPressユーザーIDごとにキャッシュを分けます。

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

アイランドはBlockstudioブロックをレンダリングできる場所ならどこでも動作します。

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

echo bs_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

ブロックタグ経由でも動作します。

HTML
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />

初期出力は引き続きアイランドマーカーとプレースホルダーです。レンダリングされたレスポンスにそのマーカーが含まれると、ランタイムが挿入されます。

PHP API

PHP
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);

marker()はブロックのメタデータを検証します。動的マーカーは、island.modeがdynamicに設定された登録済みの動的Blockstudioブロックに対してのみ作成されます。

フック

検出とマークアップ:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

エンドポイントとレンダリング:

PHP
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment

blockstudio/islands/max_per_requestは、1回のバッチエンドポイントリクエストで受け付ける動的アイランドの最大数を変更します。デフォルトは50です。

ランタイムの設定:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

シグネチャ:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

ライフサイクルアクション:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

アイランドを使用しない場合

SEOが重要なコンテンツには動的アイランドを使用しないでください。動的アイランドのフラグメントは初期HTMLに含まれず、インデックス登録を想定していません。

キャッシュ可能で、クローラーに表示する必要があるコンテンツには、通常のレンダリングまたはハイドレーション済みアイランドを使用してください。動的アイランドは、ページのシェル表示後に読み込まれるコンテンツにのみ使用してください。たとえば、アカウントUI、カートの状態、パーソナライズされたおすすめ、権限が必要なコントロールなどです。