1. プラグイン概要・アイキャッチバッジの仕組み
ECサイトにおいて、商品一覧や検索結果画面で顧客の目を引き、クリック（商品詳細への遷移）へ導くためには、サムネイル画像での「視覚的アピール」が極めて重要です。
従来の手法では、Photoshop等の画像編集ソフトで商品画像1枚1枚に「SALE」などの文字を焼き込む必要があり、セール終了後の差し戻しや文言変更に膨大な手間がかかっていました。
本プラグイン（ProductImageStickerBadge）は、商品マスター画像に手を加えることなく、EC-CUBEの管理画面からワンタッチで魅力的なリボンやバッジを商品画像の上に動的重畳表示できるソリューションです。
2. 動作要件・システム環境
本プラグインをご利用いただくための推奨システム環境は以下の通りです。
| 項目 | 動作要件・対応環境 |
|---|---|
| EC-CUBE本体 | EC-CUBE 4.2.0 〜 4.2.3 / 4.3.0 〜 4.3.x（4.2系・4.3系 双方完全対応） |
| PHP | PHP 8.1 / 8.2 / 8.3（厳格な型定義とセキュリティ規格に準拠） |
| データベース | MySQL 5.7 / 8.0 / 8.4、PostgreSQL 10 〜 16 |
| フロントエンド技術 | Pure CSS3（外部JSライブラリ依存ゼロ）、Bootstrap 5 / 4 完全対応、モバイル最適化 |
| ブラウザ | iOS Safari 最新版、Android Chrome 最新版、Google Chrome、Microsoft Edge、Safari 最新版 |
3. インストール・初期セットアップ
Zero-Config設計により、インストールして有効化するだけで標準テンプレートおよびBootstrapベースのカスタムテーマに自動適用されます。テンプレートの直接編集やレイアウト配置は不要です。
-
プラグインのインストールEC-CUBE管理画面の
オーナーズストア ＞ プラグイン ＞ プラグイン一覧より、本プラグイン（ProductImageStickerBadge）をインストールしてください。 -
プラグインの有効化一覧内の「商品画像シール・リボンバッジ」行にある歯車アイコンメニューから「有効にする」をクリックします。
-
キャッシュ削除
コンテンツ管理 ＞ キャッシュ管理より「キャッシュ削除」を実行します。 -
店舗共通設定の確認
設定 ＞ 店舗設定 ＞ 商品画像シール・バッジ設定を開き、ショップの基本形状や配置、カスタムバッジの配色をお好みに調整して「設定を保存」します。
4. 管理画面の設定項目一覧（店舗設定）
管理画面の 設定 ＞ 店舗設定 ＞ 商品画像シール・バッジ設定 では、ショップ全体の標準デザインやプリセット/カスタムバッジの管理を行います。
4-1. 基本設定（デフォルト形状・位置・パルス効果）
| 設定項目 | 初期値 | 説明 |
|---|---|---|
| プラグインの利用 | 有効 | フロント画面でのバッジ表示を一括で有効/無効に切り替えます。 |
| デフォルトデザイン形状 | 角丸ピル型（Pill） | 商品個別で指定がない場合に適用される基本形状（リボン / 丸型カプセル / 角丸四角）を選択します。 |
| デフォルト表示位置 | 左上（Top-Left） | 商品画像上の標準配置位置（左上 / 右上 / 左下 / 右下）を指定します。 |
| パルスアニメーション | 有効 | マウスホバー時にバッジが微かに脈動・拡大するアピール効果のオン/オフを設定します。 |
4-2. 表示対象画面の制御
バッジを表示させたい画面やブロックを用途に合わせて個別に制御できます。
| 設定項目 | 初期値 | 説明 |
|---|---|---|
| 商品一覧画面 | 表示する | カテゴリ別一覧や商品検索結果一覧のサムネイルにバッジを表示します。 |
| 商品詳細画面 | 表示する | 商品詳細ページのメイン画像にバッジを表示します（画像サイズに合わせて自動スケールアップ）。 |
| 新着/おすすめ商品ブロック | 表示する | トップページ等に配置された新着商品ブロック・おすすめ商品ブロックのサムネイルに表示します。 |
4-3. カスタムバッジの作成・並び替え（絵文字対応）
標準搭載の13種類のプリセット（NEW、SALE、限定、人気No.1等）に加えて、ショップ独自のオリジナルバッジを無制限に追加できます。
- 絵文字（Emoji）完全対応： 「👑 人気No.1」「❄️ クール便」「✨ 数量限定」など、テキスト欄に絵文字を直接入力・表示できます。
- 自由なカラーピッカー： 背景色（Badge Background）と文字色（Text Color）を直感的なカラーピッカーやHEXコード入力で自由に配色可能。
- 直感的な並び替え（▲/▼）： テーブル右側の「▲」「▼」ボタンでオプション番号の並び順を即座に入れ替え可能。ページ最下部の「設定を保存」で確定されます。
5. 商品登録・編集画面でのバッジ指定手順
商品管理 ＞ 商品一覧 ＞ 商品登録（または編集） 画面の下部に、本プラグイン専用のバッジ設定エリアが自動追加されます。
5-1. 番号入力（1, 2, 3...）によるクイック決定
大量の商品を効率よく登録・管理できるよう、バッジ選択欄の左端に「オプション番号入力欄」を備えています。
例えば「1」と半角数字を入力すると、セレクトボックスが自動的に「1番のバッジ（例: NEW）」へと連動し、マウスで長いドロップダウンを探す手間なくキーボード入力だけで1秒でバッジを指定できます。
5-2. 商品個別の形状・配置オーバーライド
商品の写真構図やアピール度合いに応じて、店舗基本設定とは異なるデザイン形状や表示位置を商品ごとに個別に上書き指定（オーバーライド）できます。
- 個別形状指定： 「基本設定に従う」「斜め掛けリボン」「丸型カプセル」「角丸四角」から選択。
- 個別配置指定： 「基本設定に従う」「左上」「右上」「左下」「右下」から選択。
（例: 商品写真の被写体が左上にある場合は、バッジを「右上」に指定して被写体を隠さないように配置可能）
5-3. 250px リアルタイムプレビュー機能
バッジ設定エリアの右側には、幅250pxの「リアルタイムプレビュー枠」が常時配置されています。
バッジの文言、形状、表示位置を変更した瞬間、実際にアップロードされている商品サムネイル画像の上にバッジがどのように重なるかが即座に描画されます。保存ボタンを押す前に仕上がりを確実に確認できます。
6. 3つのデザイン形状と四隅配置の仕様
ショップの世界観やブランドイメージに合わせて、最適なバッジ形状とポジションを自在に組み合わせ可能です。
| 形状名 | スタイル | 推奨用途・ビジュアル効果 |
|---|---|---|
| 斜め掛けリボン (Ribbon) |
角に45度傾斜でかかる帯状デザイン | セール（SALE）や目玉商品、期間限定品など、最も目立たせたい看板商品に最適。伝統的な高級感を演出。 |
| 丸型カプセル (Pill) |
角丸比率100%のカプセル形状 | NEW（新商品）やおすすめ、ランキング表示など、親しみやすくモダンなD2Cスタイルに最適。 |
| 角丸四角 (Badge) |
緩やかな角丸のスクエアバッジ | クール便、有機/無添加、送料無料など、商品スペックや配送条件をすっきり整然と伝えたい場合に最適。 |
7. テーマ互換性＆コンテナバインド設計
本プラグインは、サムネイル画像要素（.ec-shelfGrid__item-image や .ec-productRole__image など）の親コンテナを自動検知してバウンディングボックスを形成する「コンテナバインドCSS設計」を採用しています。
- 画像アスペクト比非依存： 正方形（1:1）はもちろん、縦長（3:4）や横長画像でも、バッジが枠外に飛び出したり余白に浮いたりせず、画像の角に完全密着します。
- 完全なPure CSS3実装： JavaScriptによる重い座標計算を行わず、CSSのGPUアクセラレーションで描画されるため、ページスクロールや表示速度（Lighthouse / PageSpeed Insights）に一切負荷を与えません。
- サードパーティテーマ対応： Bootstrap 5標準テンプレートはもちろん、主要な有料デザインテーマやフルカスタマイズテンプレートにも干渉せず調和します。
8. よくある質問・トラブルシューティング
商品登録・編集画面のバッジ選択を「なし（表示しない）」にして保存すれば、その商品にはバッジは一切表示されません。アピールしたい特定の商品のみに自由に設定いただけます。
バッジは内部で固有IDにより商品と紐付けられているため、管理画面の「▲」「▼」で並び順を変更しても、すでに商品に設定されているバッジが別のものに勝手に入れ替わってしまうことはありません。安心してお好みの順序に整理いただけます。
商品編集画面の「個別表示位置」を切り替えてください。例えば商品写真のロゴが左上にある場合は、位置を「右上」または「右下」に変更することで、写真の大切な部分を隠さずにアピールシールを表示できます。
はい、設定 ＞ 店舗設定 ＞ 商品画像シール・バッジ設定 で「プラグインの利用」を「無効」にするだけで、すべての商品バッジのフロント表示をワンクリックで一時停止できます。