EC-CUBE 4.2 / 4.3 対応

ACFカスタムフィールドプラグイン

ACF Plugin — 商品、カテゴリ、顧客、注文にプログラムコードを書かずに強力な入力フィールドを自在に追加・管理できるシステム

プラグインコード: ACF

提供元: CubeLab

1プラグイン概要

ACFカスタムフィールドプラグイン（ACF）は、EC-CUBE 4.2 / 4.3 にて、商品・カテゴリ・顧客・注文（受注）の各編集画面に独自の入力項目（カスタムフィールド）をGUI操作で自由に追加できる、WordPressの「Advanced Custom Fields」ライクな高機能拡張システムです。

入力した値はフロントエンドに自動レイアウト挿入されるほか、Twig関数を用いた個別のテンプレートカスタマイズ、標準の商品CSVエクスポート・インポート機能ともシームレスに結合されています。

主な機能特徴

4大エンティティ完全対応: 商品（Product）、カテゴリ（Category）、顧客（Customer）、注文（Order）に追加可能。
14種類の豊富に入力タイプ: テキスト、WYSIWYG（Summernote Lite）、数値、画像、カラーピッカーなどを網羅。
リピーターフィールド: 仕様表やFAQリストなど、同じ入力ブロックを何行でも繰り返し追加可能。
メディアギャラリー: 複数画像をまとめてドラッグ＆ドロップでアップロードし、直感的に並び替え可能。
条件付きロジック（Conditional Logic）: 他項目の入力値に応じた表示・非表示の動的切り替え。
Twig関数拡張: `get_custom_field_value()` 等の独自関数により、テンプレート内での柔軟な出力制御に対応。

2インストール・有効化

2-1. ファイル配置

プラグインのプログラムファイルを EC-CUBE の Plugin ディレクトリへ配置します。

/path/to/eccube/app/Plugin/ACF/   ← ここに配置

ディレクトリ名は必ず ACF （大文字）で一致させてください。

2-2. コマンドでの有効化

EC-CUBE ルートディレクトリにて以下のコマンドを実行します。

cd /path/to/eccube
php bin/console eccube:plugin:install --code=ACF
php bin/console eccube:plugin:enable --code=ACF
php bin/console cache:clear

3対応エンティティ & 表示位置

ACFプラグインは、以下の4つの主要エンティティに対してカスタムフィールドを追加可能です。

エンティティ	管理画面での入力場所	フロントエンドでの表示場所
商品 (Product)	商品管理 ➔ 商品登録・編集画面	商品詳細ページの「専用タブ」または「商品説明の下部」へ自動挿入（Twig直呼び出しも可）
カテゴリ (Category)	商品管理 ➔ カテゴリ管理画面	カテゴリ一覧やカテゴリヘッダー領域への表示（Twigテンプレート拡張）
顧客 (Customer)	会員管理 ➔ 会員登録・編集画面	マイページの会員登録情報・変更画面での表示・編集入力
注文 (Order)	受注管理 ➔ 受注登録・編集画面	注文詳細・受注メモ欄など管理者用内部情報としての表示管理

4フィールドグループの作成

複数の入力フィールドをまとめるコンテナとなる「フィールドグループ」を作成します。

メニューへアクセス

管理画面メニューに追加された 「カスタムフィールド」 ➔ 「フィールドグループ管理」 を開きます。

新規グループの追加

右上の「新規作成」をクリックし、グループ名（表示用）とグループコード（半角英数字一意）を設定します。

対象エンティティと位置の選択

このグループを追加したいエンティティ（例: 「商品」）と、フロントエンドでの自動挿入位置（「商品詳細タブ」または「商品説明下部」）を選択して保存します。

5フィールドの追加と型一覧

作成したグループの編集画面から、実際にデータ入力させるフィールド（項目）を追加します。

利用可能な14種類の入力タイプ

タイプコード	名称	詳細説明
`text`	1行テキスト	名前や簡単な短い文字列の入力に適しています。
`textarea`	複数行テキスト	改行を含む詳細なメモなどに適しています。
`wysiwyg`	WYSIWYGエディタ	Summernote Lite エディタが起動し、API Keyなしで文字装飾やHTMLテーブル編集が可能。
`number`	数値	数値を指定。最小・最大・増減ステップの設定が可能。
`select` / `radio`	選択肢	セレクトボックスまたはラジオボタンでの単一選択。
`checkbox`	チェックボックス	複数項目のチェック選択。
`date` / `datetime`	日付・日時	カレンダーポップアップによる視覚的な時間選択。
`image` / `file`	画像・ファイル	PCから画像（サムネイル付き）やPDF等のファイルをアップロード可能。
`color`	カラーピッカー	HEXカラーコードを選択入力。
`repeater`	リピーター	複数のサブフィールドを定義し、何行でも追加可能な表形式構造。
`gallery`	メディアギャラリー	複数枚の画像をまとめてアップロードし、ドラッグ順序入れ替えに対応。

6リピーター & ギャラリー

6-1. リピーターフィールド（仕様表の例）

仕様名（`text`）と仕様値（`text`）をペアにしたサブフィールドをリピーターとして作成すると、商品編集画面で「行を追加」ボタンを押すことで、テーブル行を無限に追加できます。

6-2. メディアギャラリー（ギャラリーの例）

ギャラリーフィールドを使用すると、ドラッグ＆ドロップで複数画像をアップロードし、画像をマウスドラッグするだけで任意の表示順にソート並び替えができます。

7条件付き表示（Conditional Logic）

「他フィールドの入力値」をトリガーにして、あるフィールドを表示または非表示に制御できます。

例えば、セレクトボックスで Aタイプ を選んだ場合のみ、専用の A仕様のテキスト項目 を入力フィールドとして表示させる、といったルールをGUIで何条件でも設定可能です。

8Twig関数による高度な表示カスタマイズ

自動配置だけでなく、テンプレートファイル（Twig）内で独自関数を直接記述し、任意の位置に特定のカスタムフィールドを出力することができます。

8-1. 利用可能な独自Twig関数

Twig関数	説明
`get_custom_field_value(Entity, 'フィールドコード')`	指定したエンティティ（Product, Category等）の特定フィールドの値を取得します。
`get_custom_fields(Entity)`	指定したエンティティに設定されている全カスタムフィールドのリストを取得します。
`render_custom_field_value(field, value)`	フィールド定義と値に応じた標準HTML（画像タグやテーブル等）をレンダリング出力します。

8-2. Twigでの記述コード例

例1: 特定のテキストや画像の値を個別に表示する

{# 商品詳細ページ (Product/detail.twig) などで特定フィールドを表示 #}
{% set brand = get_custom_field_value(Product, 'brand') %}
{% if brand is not empty %}
    <div class="product-brand-box">
        <span class="label">ブランド:</span>
        <span class="val">{{ brand }}</span>
    </div>
{% endif %}

例2: リピーターフィールド（仕様一覧）をループ出力する

{# リピーターフィールド (specifications) の行データをループ #}
{% set specs = get_custom_field_value(Product, 'specifications') %}
{% if specs is iterable and specs|length > 0 %}
    <table class="spec-table">
        {% for row in specs %}
            <tr>
                <th>{{ row.spec_name }}</th>
                <td>{{ row.spec_value }}</td>
            </tr>
        {% endfor %}
    </table>
{% endif %}

9CSVインポート／エクスポート

追加したカスタムフィールドのデータは、EC-CUBE標準の商品CSVダウンロードおよびアップロード機能に自動統合されます。

CSVエクスポート: 商品管理の「CSVダウンロード」を実行すると、一番右側の列に acf_field_<フィールドコード> という形式でフィールドデータが出力されます。
CSVインポート: 出力されたフォーマットに合わせてCSVを記述することで、数万件の商品に対しても一括でカスタムフィールド情報をインポート可能です。

10よくあるご質問（FAQ）

Q1. 注文や顧客のカスタムフィールドはどこに表示されますか？

A. 管理画面の「受注登録・編集画面」および「会員登録・編集画面」の対応箇所にフォーム項目が自動で差し込まれます。顧客用フィールドはマイページの情報編集画面にも表示させることができます。

Q2. フロントエンドに自動表示されません。

A. フィールドグループ設定にて「フロント表示ON」になっているか、および表示位置の設定をご確認ください。また、EC-CUBEのキャッシュをクリア（php bin/console cache:clear）してください。

Q3. リピーター内の画像をTwigで直接表示させたい。

A. リピーター内の画像フィールドはファイル名（文字列）として保持されます。/html/upload/save_image/{{ row.image_code }} のようにパスを結合して `img` タグで表示できます。