ECオープンプラットフォームとなったEC-CUBEを徹底活用!

第5回さぁ、プラグインを作ろう!

前回はEC-CUBEプラグインの仕様をできるだけ簡単に紹介しました。

今回は実際に株式会社ロックオンからリリースされているサンプルプラグインをソースレベルで読み解き、作り方を見ていこうと思います。今回は作り方がメインになりますから、まだ前回をお読みになっていない方は、プラグインの仕組みを把握する意味でも、まずお読みになることをおススメします。

今回は、本連載記事の第2回目で紹介した、カテゴリーコンテンツプラグインというサンプルプラグインを参考に、具体的に中身を見ていきます。

本記事をお読みになる前に、準備として、カテゴリーコンテンツプラグインをEC-CUBEオフィシャルサイトからダウンロードしておくと良いでしょう。

プラグイン本体のパッケージ形式

プラグインをダウンロードしてもらえればわかりますが、プラグインの拡張子は「tar.gz」となっています。この形式はUNIX系システムで主に使われる形式で、EC-CUBEのプラグインはこの形式であることが必須となっています。

EC-CUBE本体はzip形式、tar.gz形式の2つの形式がそれぞれ提供されていますが、プラグインは現状tar.gz形式のみの提供のようです。

プラグイン本体の構造

まずは、ダウンロードしたカテゴリーコンテンツプラグイン「cat_contents.tar.gz」を解凍してみましょう(tar.gz形式のファイルを展開できる環境にない方はフリーソフト等を使って解凍してください⁠⁠。

cat_contents.tar.gzの中身は以下のファイル群です。

ファイルの構成はとてもシンプルです
ファイルの構成はとてもシンプルです

画像ファイル含め複数のファイルがありますが、この中でプラグインを作る上で必須となるファイルは赤字で記載している以下の2つのみです。

  • plugin_info.php(プラグイン設定ファイル)
  • CategoryContents.php(プラグインメインクラス)

この2つがあれば基本的にはプラグインとして成り立ちます。その他のファイルはプラグインごとの何らかの処理をするためのファイルであったり、テンプレートファイルや画像ファイル等となりますので、それぞれのプラグインにより追加されるファイルということになります。

それでは、次項より各ファイルの詳しい中身を見ていきましょう。

plugin_info.php:プラグインの設定ファイル

プラグイン設定ファイルでは主に、プラグイン名やバージョンなど、プラグインに関する情報を記載します。この設定情報はプラグインのインストール時にEC-CUBEのデータベースに登録されます(一部登録されないデータもあります⁠⁠。

リスト プラグインの設定ファイルの内部ソース
class plugin_info{
    static $PLUGIN_CODE       = "CategoryContents";
    static $PLUGIN_NAME       = "カテゴリ・コンテンツ";
    static $PLUGIN_VERSION    = "0.1";
    static $COMPLIANT_VERSION = "2.12.0";
    static $AUTHOR            = "EC-CUBE開発チーム";
    static $DESCRIPTION       = "カテゴリ毎にコンテンツを設定する事ができます。画像を表示したり、文章を表示したり、自由なカスタマイズが可能です。カテゴリ管理より設定ができます。";
    static $PLUGIN_SITE_URL   = "http://www.ec-cube.net/";
    static $AUTHOR_SITE_URL   = "http://www.ec-cube.net/";
    static $CLASS_NAME       = "CategoryContents";
    static $HOOK_POINTS       = array(
        array("LC_Page_Admin_Products_Category_action_after", 'contents_set'),
        array("LC_Page_Products_List_action_after", 'disp_contents'),
        array("prefilterTransform", 'prefilterTransform'));
    static $LICENSE        = "LGPL";
}

サンプルプラグインの実際のソースでは、すべてにコメントが付いていますので、詳細な内容はそちらを参照していただければと思います。ただし、おおよそ変数名でどのような役割のものかは想像がつくと思います。

また、必須の情報は「DESCRIPTION」までの6つのみで、基本的にはそれらがあればプラグインは正常に動作します。

その後の「PLUGIN_SITE_URL」から「LICENSE」までの変数は任意の情報ということになっていますが、できればすべての情報を記載することをおススメします。というのも、たとえば「HOOK_POINTS」という変数は、フックポイントとコールバック関数を定義する変数ですが、この定数を定義すれば、register関数というものを書かずにフックポイントでの介入が可能になりますので、是非とも登録しておきたい変数です。

その他、EC-CUBEのプラグインではライセンス(⁠⁠LICENSE⁠⁠)を自由に設定できるようになっています。詳しくは割愛しますが、有料でプラグインを販売したい場合や、プラグインに他のライセンスのプログラムを入れた場合などではライセンスを検討しなければいけなくなることもあるでしょう。ちなみに、EC-CUBE公式では、EC-CUBE本体ライセンスとの相性が良い「LGPL」ライセンスが推奨とされています。

CategoryContents.php:プラグインメインクラス

サンプルプラグインであるカテゴリーコンテンツのメインクラス(処理)「CategoryContents.php」というクラスになっています。このメインクラス内では、インストール処理、アンインストール(削除)処理、有効、無効時の処理、そして、各フックポイントで動作する処理を記載します。

もちろん、メインクラスですべてを記載する必要はありません。処理が長くなるようなものは他のphpファイルを作成し、分けて記載しても問題ありません。

どのような処理が書かれているか、サンプルプラグインのメインクラスより、3つの例をピックアップし、詳しく見てみることにしましょう。

リスト インストール処理
function install($arrPlugin) {
    $objQuery =& SC_Query_Ex::getSingletonInstance();
    $objQuery->query("ALTER TABLE dtb_category ADD plg_categorycontents_category_contents TEXT");
    if(copy(PLUGIN_UPLOAD_REALDIR . "CategoryContents/logo.png", PLUGIN_HTML_REALDIR . "CategoryContents/logo.png") === false);
}

まずは、プラグインがインストールされるときの処理がこちらです。プラグインのインストール時には必ずこのメインクラスのinstall関数が呼ばれることになります。何も処理をしない場合でも、関数は作成しておく必要があります。ここでは、dtb_categoryに対してのフィールド追加と、ロゴのコピーが行われています。

逆に、アンインストール処理(uninstall)ではこの逆を書けば良いということになります。

また、このインストール、アンインストール処理の他、EC-CUBE本体の機能にある有効(enable⁠⁠、無効処理(disable)は必ず必要な関数になっています。

次に、ページクラスへのフックポイントで呼ばれる処理を見てみましょう。

リスト 商品一覧ページのページクラスへのフック処理
/**
* 商品一覧でカテゴリが指定されている場合に登録されているコンテンツを表示します.
* 
* @param LC_Page_Products_List $objPage 
* @return void
*/
function disp_contents($objPage) {
    // 選択されたカテゴリーID
    $category_id = $objPage->arrSearchData['category_id'];
    if(!empty($category_id)){
        $array_category = CategoryContents::getCategoryByCategoryId($category_id);
        $objPage->plg_categoryContents_category_contents = $array_category['plg_categorycontents_category_contents'];
    }
}

この関数は、プラグイン設定ファイルの「HOOK_POINTS」という変数にて設定されているところからわかるとおり、⁠LC_Page_Products_List_action_after」⁠商品一覧ページのページクラス処理が終わった後に動作するフックポイント)というフックポイントで動作する「disp_contents」という処理です。

処理内容としては、商品一覧ページのカテゴリーIDを取得して、それに応じたカテゴリーコンテンツ情報を返すという処理です(getCategoryByCategoryIdという処理もメインクラス内に記載されています⁠⁠。

その他、サンプルプラグインのメインクラスでは、管理画面のカテゴリ登録時のフック処理として「contents_set」という関数も記載されていますので、確認してみてください。

最後に、ページクラスへのフックではなくテンプレートへのフックを記載している部分をご紹介したいと思いますが、ここは少し長くなりますので、次項で詳しく説明します。

CategoryContents.php:プラグインメインクラス(テンプレートへのフック処理)

さて、前項まではプラグインメインクラスについてとページクラスへのフック処理について説明しました。次に、各テンプレートファイルへのフック方法を紹介します。

リスト テンプレートへのフック処理
/**
* プレフィルタコールバック関数
*
* @param string &$source テンプレートのHTMLソース
* @param LC_Page_Ex $objPage ページオブジェクト
* @param string $filename テンプレートのファイル名
* @return void
*/
function prefilterTransform(&$source, LC_Page_Ex $objPage, $filename) {
    $objTransform = new SC_Helper_Transform($source);
    $template_dir = PLUGIN_UPLOAD_REALDIR . 'CategoryContents/templates/';
    switch($objPage->arrPageLayout['device_type_id']){
        case DEVICE_TYPE_MOBILE:
        case DEVICE_TYPE_SMARTPHONE:
        case DEVICE_TYPE_PC:
            // 商品一覧画面
            if (strpos($filename, 'products/list.tpl') !== false) {
                $objTransform->select('h2.title')->insertBefore(file_get_contents($template_dir . 'categorycontents_products_list_add.tpl'));
            }
            break;
        case DEVICE_TYPE_ADMIN:
        default:
            // カテゴリ登録画面
            if (strpos($filename, 'products/category.tpl') !== false) {
                $objTransform->select('div.now_dir')->replaceElement(file_get_contents($template_dir . 'categorycontents_admin_basis_category_add.tpl'));
            }
            break;
    }
    $source = $objTransform->getHTML();
}

少しソースが長いですが、処理として具体的な記載があるのは、商品一覧画面とカテゴリ登録画面 と書かれた部分のみです。

商品一覧画面へのフック処理をもう少し詳しく見てみましょう。

$objTransform->select('h2.title')->insertBefore(file_get_contents($template_dir . 'categorycontents_products_list_add.tpl'));

この一文を分解してみます。

  1. 「'h2.title'」という部分でフックする要素を指定。
  2. 「insertBefore」という部分で、要素1の 前に という指定をしています。
  3. 「'categorycontents_products_list_add.tpl'」が上記で指定した場所に挿入するtplファイルを指しています(本tplファイルはプラグイン内に同梱されているファイルです⁠⁠。

ソースの記載方法はコピーして使いまわしで問題ありません。

上記、3つの指定をすることにより、自分が指定した場所に独自で作成したtplファイルを挿入できるということをしっかり覚えてください。

これで、テンプレートへのフックも完了です。

h2.title に独自の処理を挿入が完了
h2.title に独自の処理を挿入が完了

まとめ

いかがでしたでしょうか。

大雑把ではありますが、プラグインの設定から、ページクラスへのフックポイント、そして、テンプレートへのフックポイントと、全てをおさえることができました。

意外と簡単だと思われたのではないでしょうか?

今回ご紹介したのは、基本中の基本で、非常に簡単な処理ではありますが、ただ、このソースを応用することにより、本当にありとあらゆる処理がプラグインを利用してEC-CUBE上で行えるようになります。

初めはわからなくても、ここから徐々にステップアップすれば良いのです。

最後に

5回にわたってお送りした連載「ECオープンプラットフォームとなったEC-CUBEを徹底活用!」もこれで終了です。

今回新しくなったEC-CUBEのコンセプト「ECオープンプラットフォーム」や、そのプラットフォームの基本部分である、プラグインの紹介、そして作成まで、できるだけ分かりやすく解説したつもりです。

本記事をお読みになり、この素晴らしいプラットフォームの上で、新しいサービスやビジネスを展開していただくきっかけになれば、私としてもこれほど嬉しいことはありません。

これからのEC-CUBEの素晴らしい発展と、このプラットフォームに繰り出されるであろう皆さまの発展を期待し、本記事の締めくくりとしたいと思います。

おすすめ記事

記事・ニュース一覧