レイアウトブロック

🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

レイアウトブロック（Layout Block）：表示の仕組み、カスタマイズ方法、フォールバックの仕組み

はじめに

このドキュメントでは Layout Block（レイアウトブロック） について説明します。ソースコードを編集せずに、ストアフロントにコンテンツブロック（商品の帯、バナー、HTML の断片、プラグインが提供するブロック）を追加できる機能です。前半はサイト運営者向けで、ブロックの追加と、ブロックの見た目の変更を扱います。後半はプラグイン／テンプレートの開発者向けで、プラグインが自分のブロックを登録する方法と、表示時にシステムがファイルを選ぶ順序を扱います。読み終えると、ブロックの内容がどこから来るのか、更新で消えないようにするにはどこを編集すればよいかがわかります。

Layout Block とは

管理画面 →「コンテンツ管理」→「レイアウトブロック」（パス .../layout_block）を開きます。ここの各行が1つのブロックで、次の情報を持ちます。

項目 意味
名前（Name） 覚えやすい名前です。管理画面でだけ表示されます
位置（Position） ブロックを配置するページ上のエリア（上部、下部、左カラムなど）
ページ（Page） ブロックを表示するページの種類です。* はすべてのページを意味します
種類（Type） 内容の種類: html、view、page
内容（Text） 内容そのもの、または Type に応じたブロック／ページの名前
並び順（Sort） 同じエリアに複数のブロックがあるとき、数字が大きいほど上に表示されます
ステータス（Status） ブロックの有効／無効

内容の種類は3つです。

  1. html — Text 欄に HTML を直接貼り付けます。最も簡単で、プログラミングは不要です。
  2. view — ブロックは既存の view ファイル（テンプレートまたはプラグインが提供）です。Text 欄にはブロック名を入れます。例: shop_product_home、product_flash_sale。このドキュメントで主に扱うのはこの種類です。
  3. page — 作成済みの静的ページ（CMS）の内容を埋め込みます。

表示エリア

どのエリアがあるかはテンプレートが決めます。既定のテンプレート GP247Front は次のエリアを描画します。

エリア 場所
top ヘッダーのすぐ下、メインコンテンツの上
left / right 左カラム／右カラム（ブロックがあると、ページは自動で2カラムのレイアウトになります）
center メインコンテンツの中央
bottom コンテンツの末尾、フッターの上
footer フッターの中

既定のトップページでは、商品の帯（新着商品、セール、Flash Sale など）に bottom を使っています。

表示の仕組み：システムはどのファイルを選ぶか？

ここが中心となる部分です。view 型のブロックでは、Text 欄にはブロック名（例: product_flash_sale）だけが保存され、ファイルのパスは保存されません。表示するときになって初めて、システムは次の順序でファイルを探します。

"abc" という名前のブロックを表示する
│
├─ 1. あなたのテンプレートに専用のファイルがあるか？
│     app/GP247/Templates/{TEMPLATE_NAME}/blocks/abc.blade.php
│     → ある  ⇒ このファイルを使う。終了。
│
├─ 2. ブロック名 "abc" を登録したプラグインがあるか？
│     → ある  ⇒ プラグインの view を使う。その中で:
│           a) resources/views/vendor/Plugins/{PluginName}/…   ← あなたが上書きした版
│           b) app/GP247/Plugins/{PluginName}/Views/…          ← プラグインの元の版
│
└─ 3. どこにも見つからない ⇒ ブロックは何も表示しない（ページは通常どおり動作）。

ここからわかることは3つです。

  • あなたの版が常に優先されます。 テンプレートに同じ名前のファイルを置くだけでブロックを置き換えられます。管理画面の変更も、プラグインのコードの編集も不要です。
  • プラグインの版はフォールバック（fallback、予備）です。 カスタマイズしたファイルを削除すると、ブロックは自動でプラグインの元の版に戻ります。ページは壊れません。
  • 見つからない場合は何も表示しません。 システムは意図的に、顧客向けのページにエラーを出しません。ブロックが「消えた」場合は、下の 条件と制約 の章を確認してください。

エラーのあるブロック（例えばプラグインの不具合）は、そのブロックだけが表示されなくなります。他のブロックとページ全体は通常どおり表示されます。

ブロックをカスタマイズする（サイト運営者向け）

例として、Product Flash Sale プラグインのブロック product_flash_sale を使います。{TEMPLATE_NAME} は使用中のテンプレート名（既定は GP247Front）に、{PluginName} はプラグインのフォルダー名（例: ProductFlashSale）に置き換えてください。

⚠️ プラグインのフォルダー内のファイル（app/GP247/Plugins/...）を直接編集しないでください。 次にプラグインを更新すると上書きされ、編集した内容がすべて失われます。

方法1 — 周りに追加し、中身はそのまま（最も軽く、おすすめ）

  1. 次のパスに新しいファイルを作成します（blocks フォルダーがなければ作成してください）。

    app/GP247/Templates/{TEMPLATE_NAME}/blocks/product_flash_sale.blade.php

  2. 次の内容をファイルに貼り付け、文言を好みに合わせて変更します。

    <div class="container-x pt-6">
    <h2 class="section-title">本日のゴールデンタイム</h2>
</div>

@includeIf('Plugins/ProductFlashSale::blocks.product_flash_sale')

  3. トップページを再読み込みします。成功すると、既存の商品の帯のすぐ上に新しい見出しが表示されます。

@include ではなく @includeIf を使ってください。後でプラグインを削除した場合、@includeIf は何も表示しないだけですが、@include はページに「View not found」エラーを出します。

この方法の利点: 中身はプラグインのものなので、プラグインが見た目を更新すると、その恩恵を受けられます。

方法2 — ブロック全体を書き直す

  1. ファイルは上の手順1と同じパスに置きます。

  2. 見た目をすべて自分で書き、プラグインのヘルパー関数でデータを取得します。

    @php
    $products = gp247_product_flash(10);
@endphp

@foreach ($products as $product)
    <div>{{ $product->getName() }}</div>
@endforeach

  3. ページを再読み込みします。プラグインのブロックは完全に消え、あなたが書いた部分だけが表示されます。

方法3 — ブロック内の一部だけを変更する

ブロックには満足していて、一部（例えば商品カードだけ）を変えたいときに使います。

  1. プラグインのファイルと同じ名前・同じサブパスのファイルを、Laravel の上書き用フォルダーの下に作成します。

    resources/views/vendor/Plugins/ProductFlashSale/partials/flash_card.blade.php

    （元の版は app/GP247/Plugins/ProductFlashSale/Views/partials/flash_card.blade.php です）

  2. 商品カードの見た目を好みに合わせて書きます。

  3. ページを再読み込みします。キャッシュ削除のコマンドは不要です。新しい商品カードは、プラグインがそれを表示するすべての場所で使われます。

元に戻す

作成したファイルを削除するだけです。次のページ読み込みから、システムは自動でプラグインの版に戻ります。

比較早見表

方法1（囲む） 方法2（書き直す） 方法3（一部を変更）
手間 少ない 多い 中程度
プラグインの見た目の更新を受け取る ✅ はい ❌ いいえ 一部
向いている場面 見出し、枠、背景の追加 まったく異なるデザイン 商品カードやボタンの調整

開発者向け：プラグインが自分のブロックを登録する

プラグインを作成していて、レイアウトブロック画面にブロックを提供したい場合は、登録してください。プラグイン内にテンプレートのフォルダーを作ったり、app/GP247/Templates にファイルをコピーしたりしないでください。

手順

プラグインの Provider.php で、既存の gp247_extension_check_active() ブロックの中に次を追加します。

$blockViews = config('gp247-config.front.layout_block_views', []);
$blockViews['product_flash_sale'] = $extensionPath.'::blocks.product_flash_sale';
config(['gp247-config.front.layout_block_views' => $blockViews]);
  • キー（product_flash_sale）は、管理者が Text 欄で目にするブロック名です。
  • 値はプラグインの view キーで、実際のファイルを指します。例: app/GP247/Plugins/ProductFlashSale/Views/blocks/product_flash_sale.blade.php。

これだけです。ブロックはレイアウトブロック画面の選択リストに表示され、どのテンプレートでも表示できます。

テンプレートのフォルダーにファイルをコピーしない理由

以前の方法（インストール時にファイルをコピーする）には4つの問題があり、どれも気づかないうちに起きます。

  1. テンプレートのフォルダーが書き込み可能である必要があります。読み取り専用モードで運用しているサーバーでは、コピーの手順がスキップされます。サイト運営者にはブロックがなく、エラーも表示されません。
  2. インストール時に使用中だったテンプレートにしかコピーされません。テンプレートを変えたり、新しいストアを追加したりすると、ブロックがなくなります。
  3. プラグインを更新しても、コピーした版は更新されません。古いコピーがずっと使われ続けます。
  4. プラグインを削除すると、テンプレートのフォルダーに孤立したファイルが残ります。

登録する方法では、これらの問題は起きません。読み取り専用のサーバーでも動き、すべてのテンプレートで使え、プラグインの更新に追従し、プラグインを削除するときれいに消えます。

ブロック名の付け方

  • プラグインに応じた接頭辞を付けてください（product_flash_sale、vendor_new）。ブロック名は、テンプレートのブロックと同じ1つのフラットな名前空間を共有するためです。2つのプラグインが同じ名前を付けると、互いに上書きします。
  • 公開後にブロック名を変えないでください。 この名前はサイトのデータ（各レイアウトブロックの行の Text 欄）に保存されるため、名前を変えると、そのブロックを使っているサイトでブロックが消えます。

技術メモ

  • 管理画面の選択リストとストアフロントでの表示は、同じ情報源を同じ優先順位で読みます。そのため、選択リストが、実際に表示されるものと違うものを提示することはありません。
  • ブロックが登録されるのは、プラグインが有効なときだけです。プラグインを無効にしても、レイアウトブロックの行はデータに残りますが、何も表示されません。有効に戻すとブロックも戻ります。

条件と制約（操作の前に確認）

Layout block の行を作成するとき

  • 位置（Position）は、テンプレートが実際に描画するエリアでなければなりません。 位置の一覧と、テンプレートが呼び出すエリアは別のものです。テンプレートが使わない位置を選ぶと、ブロックは保存に成功し、一覧にも表示されますが、ページには何も出力されません。GP247Front で判明しているケース: 位置 top_site はどのテンプレートでも描画されません。<head> エリアにコードを挿入したい場合、現在この画面からは選べません。
  • ページ（Page）にはパスではなく、ページの種類を指定します。 ページ欄には、ページの種類のコード（front_home、shop_product_detail、shop_cart など）か、すべてのページを表す * を入れます。パスや CMS ページの名前を入れても一致することはなく、ブロックは表示されません。
  • ブロック名（Text）は一覧から選んでください。 Type = view で存在しない名前を入力すると、システムはファイルを見つけられず、ブロックをスキップします。エラーメッセージは表示されません。

ブロックが表示されないとき

次の順に確認してください。よくある原因は次の4つです。

  • ブロックが無効になっている — ステータス（Status）列をオンにする必要があります。
  • ブロックが別のストア・別のテンプレートに属している。 レイアウトブロックの各行は、1つのストアと1つのテンプレートに結び付いています。ストアのテンプレートを変えると、以前のテンプレート用に作成した行は表示されなくなります（削除はされません。以前のテンプレートに戻せば表示されます）。
  • ブロックを提供するプラグインが無効になっている、または削除されている — ブロックは消えますが、レイアウトブロックの行は残ります。
  • 位置またはページの種類が間違っている — すぐ上の項目を参照してください。

ブロックの見た目をカスタマイズするとき

  • ファイル名はブロック名と完全に一致させてください: blocks/{block name}.blade.php。1文字でも違うと、システムはあなたのファイルを無視してプラグインの版を使います。「編集が反映されない」と勘違いしやすい点です。
  • テンプレート名は大文字と小文字を区別し、app/GP247/Templates/ 内のフォルダー名と正確に一致させる必要があります。
  • プラグインのフォルダー内のファイルを直接編集すると、プラグインの更新時に失われます。 必ず上の3つの方法のいずれかを使ってください。
  • 方法2と方法3は固定されたコピーを作ります。 後でプラグインが見た目を改善しても、上書きした部分にはその変更が反映されません。方法1にはこの欠点がありません。

よくある質問（Q&A）

Q1: プラグインのフォルダー内のファイルを編集していましたが、プラグインを更新したらすべて消えました。元に戻せますか？

→ 自動では復元できません。残したい内容を app/GP247/Templates/{TEMPLATE_NAME}/blocks/{block name}.blade.php にコピーし直してください。それ以降、プラグインの更新がこのファイルに触れることはありません。

Q2: カスタマイズ用のファイルを作成したのに、ページには古い版が表示されます。なぜですか？

→ 次の3点を確認してください。ファイル名が {block name}.blade.php と一致しているか、テンプレートのフォルダー名がストアで使用中のテンプレート名と一致しているか、ファイルが blocks フォルダーの中にあるか。それでも解決しない場合は、php artisan optimize:clear を実行してから再読み込みしてください。

Q3: プラグインを削除すると、囲んだブロックのせいでページが壊れますか？

→ @includeIf を使っていれば壊れません。ページにはあなたが書いた部分だけが表示され、プラグインの部分はスキップされます。誤って @include を使っている場合は、@includeIf に直してください。

Q4: サイトで自作のテンプレートを使っています。プラグインのブロックは動きますか？

→ はい。プラグインが登録したブロックはすべてのテンプレートで動きます。追加でファイルを作成する必要はありません。

Q5: 複数のストア（マルチストア）があります。ブロックは何回作成する必要がありますか？

→ ストアごとに1行ずつ作成します。各行が1つのストアと1つのテンプレートに結び付いているためです。プラグインのブロックは、プラグインが有効であればすべてのストアで使えます。

Q6: 2つのプラグインが同じブロック名を付けた場合はどうなりますか？

→ 後から登録したものが先のものを上書きし、選択リストには1つしか残りません。そのため、開発者はプラグインに応じた接頭辞をブロック名に付けるべきです。

Q7: ブロックにエラーがあると、ページ全体が止まりますか？

→ いいえ。エラーはそのブロックの範囲に閉じ込められます。ブロックは表示されませんが、ページの残りの部分は通常どおり動き、エラーはシステムログに記録されます。

Q8: トラッキングコード（Google Analytics、Facebook Pixel）をページに挿入するにはどうすればよいですか？

→ Type = html のブロックを作成し、Text 欄にコードを貼り付け、Page = * と、テンプレートが実際に描画する位置（例: footer）を選びます。条件と制約 の章に注意してください。位置 top_site は現在表示されません。

Q9: レイアウトブロックを使わずに、ブロックをテンプレートに直接固定できますか？

→ できます。テンプレートのファイルの、表示したい場所に @includeIf('Plugins/{PluginName}::blocks.{block name}') を1行追加します。

Q10: レイアウトブロックの行を削除すると、内容も失われますか？

→ Type = html の場合、内容はその行の中にあるため失われます。先に別の場所へコピーしてください。Type = view と Type = page の場合、行はファイルやページを指しているだけなので、行を削除しても何も失われません。

📅 最終更新: 2026-10-22 · ✍️ 作成者 (Author): GP247