仕入注文

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

GP247 のテンプレート（ストアフロントのデザイン）作成ガイド

はじめに

このドキュメントでは、GP247 の新しいテンプレート（ストアフロントのデザイン）を作成する方法を説明します。 対象は、GP247 のネットショップのデザインを自分で作りたい PHP/Laravel 開発者です。読み終えると、テンプレートの雛形を生成するコマンドの使い方、 フォルダー構成、トップページや固定ページの作り方がわかります。そして最も重要な点として、テンプレートが gp247/shop とどう連携するか （ビューのフォールバックの仕組み）を理解できます。これにより、ショップのページを自分で書き直す必要があるかどうかを判断できます。

⚠️ 注意: 作業を始める前に覚えておくべき最も重要な 2 点：

  1. テンプレートは gp247/front がインストールされている場合にのみ使えます。 テンプレートはストアフロントのデザインであり、 ストアフロント全体は gp247/front パッケージが提供しています。そのため、テンプレートの gp247.json には常に requireComposerPackages: ["gp247/front"] が宣言されています。gp247/front がなければ、テンプレートは機能しません。
  2. サンプルテンプレートには gp247/shop のビューが含まれていません。 新しいテンプレートにショップのページ （商品一覧、カート、決済など）のビューがない場合、gp247/shop はフォールバックの仕組み（6 章）により、パッケージ内のデフォルトのビューを自動で使います。 これらのページを自分で書く必要があるのは、カスタマイズしたい場合だけです。その場合は、**gp247/shop のビューをパブリッシュ（書き出し）**して、新しいテンプレート用に編集するとよいでしょう。

💡 ヒント: AI エージェントと一緒に作業しますか？ gp247-skills リポジトリのスキル gp247-template-create を使ってください（スキルのフォルダーをエージェントのスキルフォルダー、 例えば Claude Code なら .claude/skills/ にコピーします）。このスキルはサイトのバージョンを自動で調べ、gp247:make-template で雛形を生成し、 テンプレートに必要なファイルをすべて、アップデートに安全な方法で作成します。

1. 準備

始める前に、次のものが必要です。

  1. gp247/core（2.0 以上）と gp247/front がインストールされた GP247 の Web サイト。商品を販売するサイトなら、 通常は gp247/shop もインストールされています。
  2. サーバーまたは開発マシンで php artisan コマンドを実行できる権限（ターミナル／コマンドライン）。
  3. （推奨）テンプレートの Tailwind CSS を自分でコンパイルしたい場合は Node.js。5.4 節を参照してください。

用語の早見表：

  • テンプレート：ストアフロント（お客様が見るページ）のデザイン一式です。各ストアは有効なテンプレートを 1 つ選びます。
  • gp247/front：ストアフロント（ルート、コントローラー、テンプレートの仕組み）を提供するパッケージです。テンプレートを動かすには必須です。
  • gp247/shop：販売用のパッケージ（商品、カート、決済）です。必須ではありませんが、ある場合はテンプレートでショップのページのデザインをカスタマイズできます。
  • configKey：テンプレートの一意の識別子です。テンプレートのフォルダー名と完全に一致します。
  • ビュー（Blade）：Laravel の画面ファイル .blade.php です。

2. artisan コマンドでテンプレートの雛形を生成する

gp247/front には、v2 標準のテンプレートの雛形を生成するコマンドがあります。ファイルを 1 つずつ手で作る必要はありません。

  1. GP247 の Web サイトのルートフォルダー（artisan ファイルがある場所）でターミナルを開きます。

  2. 次の行をそのまま入力して Enter を押します（MyShopSkin は作りたいテンプレート名に置き換えてください）。

    php artisan gp247:make-template --name=MyShopSkin --download=0

    パラメーターの意味：

    • --name=MyShopSkin：テンプレート名です。PascalCase（各単語の先頭を大文字にし、アクセント記号やスペースを使わない）で書くことをおすすめします。
    • --download=0：テンプレートを app/GP247/Templates/MyShopSkin に直接作成します（すぐに使えます）。--download=1 の場合、配布用のパッケージとして storage/tmp に .zip ファイルを作成します。

  3. 成功すると、ターミナルに人が読める 1 行のテキスト（例：Success）が表示されます。 app/GP247/Templates/MyShopSkin フォルダーがサンプルファイル一式とともに作成されます。--json を付けると、 機械が読めるエンベロープが得られます。

    {"ok":true,"command":"gp247:make-template","data":{"key":"MyShopSkin","path":"","msg":"Success"},"warnings":[],"error":null}

    （--download=1 の場合、zip のパスは data.path にあります。）

3. テンプレートのフォルダー構成

雛形を生成すると、テンプレートは次のような構成になります（各部分の役割を説明しています）。さらに、 実際に稼働している完全なテンプレートには、通常 layout/、screen/、partials/、components/、livewire/ などの画面用フォルダーもあります。

app/GP247/Templates/MyShopSkin/
├── blocks/          # 再利用できる UI ブロック（バナー、コンテンツブロックなど）、LayoutBlock 用
├── Lang/
│   ├── en/lang.php  # 英語の言語文字列
│   └── vi/lang.php  # ベトナム語の言語文字列
├── Plugins/         # （任意）テンプレートに同梱するプラグイン
├── public/          # 静的アセット（css/js/画像）。インストール時に public/GP247/Templates/MyShopSkin にコピーされる
├── AppConfig.php    # メインの設定ファイル：install/uninstall/enable/disable/setupStore
├── config.php       # テンプレートのデフォルト設定（アップデート時に上書きされる — 7 章を参照）
├── function.php     # テンプレートのヘルパー関数
├── gp247.json       # ⭐ テンプレート情報の宣言（特に requireComposerPackages）
├── Provider.php     # サービスの登録（ビュー、言語、設定など）
└── Route.php        # テンプレート独自のルート（必要な場合）

# 自分で追加する画面用フォルダー（実際に稼働しているテンプレートと同様）：
├── layout.blade.php # 全体のレイアウト（ヘッダー + コンテンツ + フッター）
├── layout/          # レイアウトの部品（ヘッダー、フッター、メニューなど）
├── screen/          # 各ページ：home、page_detail、404 など（上書きしたい場合は shop_* も — 6 章）
├── partials/        # 再利用できる画面の部品
├── components/      # テンプレート独自の Blade コンポーネント
└── livewire/        # Livewire コンポーネント用のビュー（カート、商品フィルターなど）

ビューのパスについての注意：テンプレートのビューは、GP247 によって特別な名前空間 GP247TemplatePath::<TemplateName>.<path> に登録されます。例えば、テンプレート MyShopSkin のファイル screen/home.blade.php は GP247TemplatePath::MyShopSkin.screen.home として呼び出されます。自分で登録する必要はありません。 gp247/front が app/GP247/Templates 全体を自動でスキャンします。

4. gp247.json を宣言する

gp247.json を開きます。生成されたサンプルの内容は次のとおりです。

{
    "name": "MyShopSkin module",
    "image": "images/logo.jpg",
    "auth": "GP247",
    "email": "support@gp247.net",
    "link": "https://GP247.net",
    "configGroup": "Templates",
    "configCode": "MyShopSkin",
    "configKey": "MyShopSkin",
    "version": "1.0",
    "requireCore": ["3.1"],
    "requireUpdateFrom": "1.0",
    "requireComposerPackages": ["gp247/front"],
    "requireGp247Extensions": []
}

重要なフィールドの意味：

フィールド 意味
configGroup テンプレートでは常に "Templates" です。
configKey 一意の識別子で、テンプレートのフォルダー名と一致します。 リリース後は変更しないでください。
version バージョン（semver：1.0、1.1 など）。新しいリリースごとにこの番号を上げる必要があります。
requireCore 動作するコアのバージョンです。php artisan gp247:info の core 行の値を書きます（例：["3.1"]）。各値 "X.Y" は「X.x 系の中で X.Y 以上」という範囲を表します。"2.1" は 3.x のコアで拒否されます。
requireComposerPackages 常に "gp247/front" を含めます。テンプレートはストアフロントがある場合にのみ動作するためです。販売サイト専用のテンプレートなら "gp247/shop" も追加します。
requireUpdateFrom このバージョンへのワンクリックアップデートを許可する最低バージョンです。"1.0" にしておけば安全です。

gp247/core 2.1 からのキー名の変更： requirePackages → requireComposerPackages、requireExtensions → requireGp247Extensions。Core 2.1 は旧キーも読み込みます（後方互換）が、非推奨です。新しいテンプレートでは新しいキーを使ってください（requireComposerPackages には常に "gp247/front" を含めます）。

5. テンプレートのデザインを作る

5.1. AppConfig.php — テンプレートのライフサイクル

このファイルは ExtensionConfigDefault を継承し、サイトオーナーがテンプレートをインストール／アンインストール／有効化／無効化したときの処理を定義します。 プラグインとの違いは、メソッド setupStore($storeId) でテンプレートをストアに割り当てる点です（AdminStore の template 列を更新します）。 生成された雛形はそのまま動作するので、通常は独自のロジックを追加するだけです。

5.2. 全体レイアウトと各ページ

  • layout.blade.php（または layout/）：<head>、ヘッダー、コンテンツ領域、フッターを含む全体の枠です。
  • screen/：個々のページです。例：home.blade.php（トップページ）、page_detail.blade.php、 404.blade.php、front_search.blade.php。
  • partials/、components/：再利用できる画面の部品です。

5.3. 動的な画面 — Livewire/Alpine を使い、jQuery は使わない

GP247 2.0 は Tailwind + Alpine + Livewire を使います。動的な操作（カート、商品フィルターなど）は Livewire コンポーネントで作り、そのビューは livewire/ に置きます。古い jQuery/Bootstrap のウィジェットは使わないでください。 表示する文字はすべて gp247_language_render(...) / trans(...) で出力し、ハードコードしないでください。

5.4. アセットと Tailwind CSS

  • 静的アセット（css/js/画像）はテンプレートの public/ に置きます。インストール時に public/GP247/Templates/MyShopSkin にコピーされます。
  • GP247 は事前コンパイル済みの Tailwind を使います（実行時の JIT ではありません）。テンプレートに新しい Tailwind のクラスを追加した場合は、 Node.js（npx tailwindcss ...）で CSS ファイルを自分で再コンパイルし、出力をコミットする必要があります。 既存のクラスを再利用するだけなら、再ビルドは不要です。

6. ⭐ テンプレートと gp247/shop — ビューのフォールバックの仕組み（よく読んでください）

ここがこのドキュメントで最も重要な部分です。「新しいテンプレートに商品ページやカートページがないと、ネットショップは壊れますか？」 という疑問に答えます。答えは**「壊れません」**です。

6.1. 仕組み

お客様が gp247/shop が処理するページ（例：商品一覧）を開くと、ショップのコントローラーは決まったビューファイルを直接呼び出すわけではありません。 ビューを選ぶ関数 gp247_shop_process_view() を通して呼び出し、この関数は次のように動作します。

  1. まず、有効なテンプレートのビューを探します。 例えばテンプレートが MyShopSkin なら、 GP247TemplatePath::MyShopSkin.screen.shop_product_list（つまりファイル app/GP247/Templates/MyShopSkin/screen/shop_product_list.blade.php）を探します。
  2. テンプレートにそのファイルがあれば → それを使います（テンプレートがショップの画面を「上書き」している状態）。
  3. テンプレートにない場合 → ショップパッケージのデフォルトのビューにフォールバックします： gp247-shop-front::screen.shop_product_list（つまりファイル vendor/gp247/shop/src/Views/templates/GP247Front/screen/shop_product_list.blade.php）。

結果として： ショップのページを1 つも含まない新しいテンプレートでも、ネットショップは通常どおり動作します。 ショップのページはすべて、gp247/shop パッケージのデフォルト版を自動で使います。これが、サンプルテンプレートにフロントのページ （home、page_detail、404 など）だけがあり、shop_* がない理由です。

6.2. テンプレートでショップのページを自分で書く必要があるのはいつ？

デフォルトとは違うショップのデザインにしたい場合だけです（独自の商品一覧のレイアウト、自分のスタイルのカートページなど）。 その場合は、ショップのビューを自分のテンプレートの中に作り、ショップが期待するサブパスに正しく置きます。上書きできるショップのページの一覧です（テンプレートの screen/ に置きます）。

テンプレートに置くファイル 対応するページ
screen/shop_product_list.blade.php 商品一覧
screen/shop_product_detail.blade.php 商品詳細
screen/shop_cart.blade.php カート
screen/shop_checkout.blade.php 決済
screen/shop_wishlist.blade.php お気に入り
screen/shop_compare.blade.php 商品比較
screen/shop_search.blade.php 検索
screen/shop_order_success.blade.php 注文完了

screen/ のほかにも、ショップパッケージには同じように上書きできるビューのフォルダーがあります（account/、auth/、 blocks/、common/、livewire/）。ショップパッケージと同じサブパスで、テンプレートの中に置いてください。

6.3. 完全なテンプレート（ショップを含む）を参考にする方法：gp247/shop のビューをパブリッシュする

ショップのページをゼロから書かずに済むよう、**gp247/shop のデフォルトのビューをパブリッシュ（書き出し）**して参考にし、 自分のテンプレートにコピーして編集します。

  1. 編集したいファイルを 1 つずつ取り出します（推奨の方法）。

    php artisan gp247:template-publish GP247Front --file=screen/shop_product_list.blade.php

    ファイルは app/GP247/Templates/GP247Front/screen/shop_product_list.blade.php に置かれます。ツリー全体を書き出したい場合は、 php artisan vendor:publish --tag=gp247:shop-view-front も使えます。ただし、下の注意を必ず読んでください。

  2. ショップのページの構造を読むだけなら、何もパブリッシュする必要はありません。 vendor/gp247/shop/src/Views/templates/GP247Front/（screen/shop_*.blade.php、account/、auth/、 blocks/、common/、livewire/、partials/）と、フロント側の vendor/gp247/front/src/Views/templates/GP247Front/ を直接開いてください。これらが実際に描画されているファイルです。

⭐ total-method プラグイン（クーポン／ポイント）は、決済のビューを上書きしない場合に自動で動作します。 gp247/shop のデフォルト版がすでに total-method の領域を描画しています（推奨の方法）。決済ウィザードのビュー （livewire/shop_checkout-wizard.blade.php）を上書きしてデザインを変える場合だけ、確認ステップにある total-method 領域の 2 つの include を残す必要があります： @include('gp247-shop-front::partials.checkout_total_methods') と @include('gp247-shop-front::partials.order_totals')。これらは、すべてのクーポン／ポイントのプラグイン（コントラクト CheckoutTotalMethod）を汎用的に描画します。削除すると、すべての total-method プラグインのコード入力欄が何の警告もなく消えます。 これらが描画する部品には、テンプレートのビルド済み CSS にすでにある UI クラスだけを使ってください （まったく新しい Tailwind のクラスはビルド済み CSS に存在しません）。

  1. カスタマイズしたいショップのページのファイルを、サブパスを変えずに自分のテンプレートにコピーします。 例えば、MyShopSkin の商品一覧ページをカスタマイズする場合：

    コピー元:  app/GP247/Templates/GP247Front/screen/shop_product_list.blade.php
コピー先:  app/GP247/Templates/MyShopSkin/screen/shop_product_list.blade.php

    その後、MyShopSkin 内のファイルを自由に編集します。6.1 の仕組みにより、gp247/shop はあなたのテンプレート内の版を優先して使います。 コピーしなかったショップのページは、引き続きデフォルト版が自動で使われます。

💡 ヒント: 本当に変えたいページだけをコピーしてください。一式をコピーして何も編集しないままにすると、無駄な保守の負担になります （ショップパッケージがアップデートされても、テンプレートに残した版は自動で更新されません）。

⚠️ 注意: 本当に変えたいページだけをコピーしてください。 2026-09-14 から、テンプレートの Blade は gp247/front / gp247/shop から直接提供されます。ファイルが app/ の下に置かれるのは、あなたがパブリッシュしたときだけです。そしてその時点から、そのファイルは パッケージの版を永久に覆い隠し、composer update でそのファイルが修正されることは二度とありません。ツリー全体をパブリッシュする （--tag=gp247:shop-view-front、--tag=gp247:front-view）と、すべてのファイルが一度に固定されます。 php artisan gp247:template-prune GP247Front --dry-run で、パブリッシュ済みでもパッケージの版とまったく同じで、パッケージに戻せるファイルを一覧表示できます。

タグの違い：gp247:shop-view-front はストアフロントのビュー（テンプレート用）です。一方、 gp247:shop-view-admin はショップの管理画面のビューで、ストアフロントのテンプレートとは関係ありません。 混同しないでください。

7. バージョンのアップデート（アップデートに安全な作り方）

テンプレートは、プラグインと同じワンクリックアップデートの仕組みを使います。アップデート時、システムはテンプレートのすべてのファイルを上書きしますが、 データベース（admin_config）はそのまま残します。そのため、プラグインとまったく同じ安全の原則がテンプレートにも当てはまります。

  • version はリリースごとに上げる必要があります。configKey は変更しません。
  • config.php にはデフォルト値だけを書きます（アップデート時に上書きされます）。サイトオーナーの選択はすべて admin_config に保存する必要があります。
  • バージョン間でデータ構造を変える場合は、フック AppConfig::update($fromVersion) で移行します。
  • ユーザーがアップロードしたファイルをテンプレートのフォルダー内に保存しないでください。

アップデートに安全な仕組みの詳細は、ドキュメント アップデートに安全なプラグインを参照してください。原則はまったく同じです。

8. インストールと確認

  1. Laravel のキャッシュを削除して、新しいルート・ビュー・設定を読み込みます。

    php artisan optimize:clear

    成功すると、ターミナルに ... cleared successfully のような行が表示されます。

  2. テンプレートをインストールします。次の 2 つの方法から 1 つを選びます。

    • 管理画面で： テンプレートメニューを開き、自分のテンプレートを見つけて**「インストール」**(Install) を押します。

    • コマンドラインで： テンプレートのフォルダーはすでに app/GP247/Templates/MyShopSkin にあるので、コマンドはその場で インストールします。何もダウンロードせず、API ライセンスも不要です。

      php artisan gp247:ext-install --type=template --key=MyShopSkin
php artisan gp247:ext-list --type=template

      2 つ目のコマンドで、テンプレートがインストール済みの状態になったことを確認します。テンプレートを別のサイトに持っていくときは、 フォルダーを .zip に圧縮し、php artisan gp247:ext-install --type=template --file=MyShopSkin.zip でインストールします。

  3. ストアでテンプレートを有効化します。管理画面 → **「システム管理」→「サイト情報」を開き、「テンプレート」**欄で テンプレートを選んで確認を押します。この手順には CLI コマンドがありません。

    ⚠️ 注意: テンプレートを変更すると、旧テンプレートのトップページのレイアウトブロックとバナーが削除され、サンプルデータが読み込まれます。 販売中のサイトではなく、開発用のサイトで試してください。詳しくは：プラグイン・テンプレートのインストール — 6 章。

  4. Web サイトのトップページを開き、新しいテンプレートのデザインを確認します。gp247/shop がある場合は、商品一覧ページと カートページも開いてみてください。まだ上書きしていなければ、ショップのデフォルトのデザインで表示されます（想定どおりの動作です）。

  5. テンプレートが対応している場合は、スマートフォンでの表示（レスポンシブ）とダークモードでの表示も確認してください。

9. リリース前のチェックリスト

  • gp247.json：configGroup = "Templates"、configKey がフォルダー名と一致、requireComposerPackages に "gp247/front" がある。
  • version を前のリリースから上げた（アップデート版の場合）。
  • デザインに Tailwind + Livewire/Alpine を使っている。古い jQuery/Bootstrap のウィジェットは残っていない。
  • すべての文字を gp247_language_render(...) / trans(...) で出力し、ハードコードしていない。vi と en の両方がある。
  • 新しい Tailwind のクラスを追加した場合：CSS を再コンパイルし、出力を public/ に含めた。
  • どのショップのページを上書きするか（テンプレートの screen/ にコピー）、どのページをデフォルトのフォールバックのままにするかを明確に決めた。
  • config.php にはデフォルト値だけがあり、サイトオーナーの選択は admin_config にある（アップデートに安全）。
  • php artisan optimize:clear を実行し、インストール（管理画面または gp247:ext-install --type=template）と **「サイト情報」**での有効化に成功した。トップページとショップのページが正しく表示される。
  • レスポンシブ（スマートフォン）とダークモード（対応している場合）を確認した。

10. よくある質問（Q&A）

Q1: テンプレートをインストールしたのに、何も変わりません。

→ Web サイトに gp247/front がインストールされていない可能性が高いです。テンプレートはストアフロントのデザインなので、 gp247/front がある場合にのみ動作します。先に gp247/front をインストールしてください。

Q2: 新しいテンプレートに商品ページやカートページがないと、ネットショップは壊れますか？

→ 壊れません。テンプレートにないページについては、gp247/shop がパッケージ内のデフォルトのビューを自動で使います（フォールバック）。 Web サイトは通常どおり販売を続けられます。6.1 節を参照してください。

Q3: カートページを自分独自のデザインで表示するには？

→ 自分のテンプレートの中に screen/shop_cart.blade.php ファイルを作ります。gp247/shop はデフォルト版の代わりにこのファイルを優先して使います。 6.2 節のパスの表を参照してください。

Q4: ショップのページも含めた完全なテンプレートを参考に見たいのですが、どうすればよいですか？

→ php artisan vendor:publish --tag=gp247:shop-view-front を実行します。このコマンドは、ショップのデフォルトのストアフロント用ビューをすべて app/GP247/Templates/GP247Front に書き出すので、見たりコピーしたりできます。6.3 節を参照してください。

Q5: パブリッシュした後、すべてを自分のテンプレートにコピーする必要がありますか？

→ おすすめしません。デザインを本当に変えたいページだけをコピーしてください。コピーしなかったページは自動でデフォルト版を使います。 すっきりしますし、ショップパッケージのアップデートも受けやすくなります。

Q6: ショップのファイルを間違った場所に置くとどうなりますか？　無視されますか？

→ はい、無視されます。フォールバックの仕組みは正確なサブパス（例：screen/shop_product_list.blade.php）で探します。名前やフォルダーを間違えると、 システムはテンプレートにそのファイルがないとみなし、デフォルト版を使います。

Q7: gp247:shop-view-front と gp247:shop-view-admin の違いは何ですか？

→ gp247:shop-view-front はストアフロントのビューです（テンプレート用で、あなたに必要なものです）。gp247:shop-view-admin はショップの管理画面のビューで、お客様向けのテンプレートとは関係ありません。

Q8: テンプレートをアップデートすると、サイトオーナーの設定が消えますか？

→ 正しく作っていれば消えません。アップデートはファイルを上書きしますが、データベースは残します。サイトオーナーの選択はすべて admin_config に保存し、config.php（上書きされるファイル）には保存しないでください。7 章を参照してください。

Q9: 新しい Tailwind のクラスを追加したのに、デザインが変わりません。

→ GP247 は事前コンパイル済みの Tailwind を使っており、JIT ではありません。まだビルドされていない新しいクラスは効果がありません。 CSS ファイルを再コンパイル（npx tailwindcss ...）すると反映されます。

Q10: ビューを編集したのに、ページに古い版が表示されます。

→ php artisan optimize:clear を実行してビュー・ルート・設定のキャッシュを削除し、ページを再読み込みしてください。Laravel が古いキャッシュを保持していることが原因で、 最もよくあるトラブルです。

変更履歴

日付 GP247 バージョン 変更内容
2026-10-18 gp247/core 3.1 修正： requireCore を稼働中のコア（php artisan gp247:info）に合わせて記載 — 旧値 "2.1" は 3.x のコアで拒否されます。章のタイトルから、章番号と食い違っていた「ステップ」番号を削除

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