「ver4/プラグイン作成ガイド」を編集中

<metadesc>baserCMS は、独自のプラグイン管理機能を持ち、プラグインのインストール、有効化、無効化の仕組み、また、本体での処理を横取りするイベント機能を提供しています。</metadesc>

baserCMS は、独自のプラグイン管理機能を持ち、プラグインのインストール、有効化、無効化の仕組み、また、本体での処理を横取りするイベント機能を提供しています。<br /> 基本的には、CakePHP のプラグイン開発に準じ、CakePHP用のプラグインも利用する事ができますが、baserCMS の管理機能に認識させる為には、baserCMS独自のルールを組み込む必要があります。

## CakePHP のプラグイン開発に準じてプラグインを開発する

前述したとおり、baserCMS は基本的に CakePHP の開発手法に準じて開発されていますので、プラグインについても CakePHP の開発に準ずる必要があります。 CakePHP のプラグイン開発については次のリンク先を参考にしてください。

* [CakePHP - プラグイン][1]

## コントローラーの利用

コントローラーでは、baserCMS にパッケージされている AppController を継承します。<br /> これにより、baserCMSコントローラーの基本機能が実装できます。

<syntaxhighlight lang="php">
class DemoController extends AppController {
}</syntaxhighlight>

## モデルの利用

プラグインで利用するモデルでは、baserCMS にパッケージされている AppModel を継承させます。<br /> これにより、baserCMSモデルの基本機能が実装できます。

<syntaxhighlight lang="php">
class Demo extends AppModel {
}</syntaxhighlight>

## ビューの利用とプレフィックス

プラグインでビューを利用する場合には、特別なルールはありません。エレメントを利用する場合には、テーマのエレメントで問題なく上書きできるように、ファイル名の先頭にプラグイン名をプレフィックスとして追加しましょう。

テーマ内にプラグインのエレメントと同名のエレメントを配置することで、プラグインのエレメントを直接書き換えず、カスタマイズすることができるのですが、他のプラグインで、同名のエレメントが存在する場合、どちらか片方のエレメントしか上書きできなくなってしまうためです。

<pre>Sample プラグインに single エレメントを配置する場合

 /PluginName/View/Elements/sample_single.php</pre>

## ヘルパーの利用

プラグインでもヘルパーを利用する事ができますが、テーマと違い、配置しただけでは利用できませんので注意が必要です。<br /> プラグインで呼び出すには、コントローラーに利用するヘルパーを定義します。

baserCMSのコアでヘルパーを利用する為には、イベントを利用します。<br /> コントローラーイベントの startup や initialize で、ヘルパーの追加処理を記述します。

## インストール用のスキーマと初期データを準備する

データベースを利用するプラグインの場合は、テーブル定義用のスキーマファイルを用意します。また、初期データを登録する場合は、CSVファイルで作成します。

### スキーマファイル、初期データの作成と設置

スキーマファイルの作成は「データメンテナンス」を利用する事で簡単に行う事ができます。<br />
<small>※ スキーマファイルとは、CakePHPで利用できる形式のデータベーステーブルの定義ファイルです。</small>

#### １．データベースに任意のテーブルを作成する

データベースは MySQL をベースに開発を行なってください。<br /> MySQLを利用する事により、適切なスキーマファイルを生成する事ができます。

テーブル名は、インストール時に設定したプレフィックスと、純粋なテーブル名の間にプラグイン用のプレフィックス「pg_」を付加します。

<pre>（例）インストール時のプレフィックスが「bc_」で、純粋なテーブル名が、「pens」の場合
　　　　bc_pg_pens</pre>

<small>※ SQLiteはインストール時のプレフィックスはありません。</small>

テーブルには基本的に次のフィールドを含めてください。

* id・・・一意のID番号（プライマリーキー用）
* created・・・レコード作成日（自動更新されます）
* modified・・・レコード更新日（自動更新されます）

#### ２．データを登録する

管理システムから、またはデータベースに直接、インストール時の初期値となるデータを登録します。

#### ３．データメンテナンスよりバックアップデータをダウンロードする

データメンテナンスから、テーブル定義の元となるスキーマファイルと、初期データの元となるCSVファイルのセットがダウンロードできます。

#### ４．生成されたスキーマファイルを設置する

インストール時に実行するスキーマファイルは以下のパスに設置します。

<pre>{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Config/Schema/{プレフィックスなしのテーブル名}.php
</pre>

#### ５．生成されたCSVデータのクリーニングを行う。

id / created / modified の値を手作業で空にして保存します。

#### 6．作成したCSVファイルを設置する

インストール時に実行するCSVファイルは以下のパスに設置します。

<pre>{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Config/data/default/{プレフィックスなしのテーブル名}.csv
</pre>

### 初期データファイルの仕様

初期データファイルはCSVファイルで作成します。CSVファイルは次の仕様となります。

* 文字コードは、Shift-JIS
* 各フィールドをカンマで区切る
* 各フィールドをダブルコーテーション（")で囲む
* フィールド内のダブルコーテーションは、ダブルコーテーションでエスケープする
* １行目は、フィールド名の定義とする
* id / created / modified の値は空にする

<pre>（例）
"id", "name","title","created","modified"
"","test","簡単な""プラグイン""の作り方","",""
</pre>

## インストール用設定ファイルを準備する

インストール画面で利用する設定値を記述する設定ファイルは、config.php というファイル名で以下のパスに設置します。

<pre>{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/config.php</pre>

設定ファイルには下記の設置値を記述します。

<syntaxhighlight lang="php">$title = '{プラグイン名（日本語可）}';
$description = '{プラグインの説明文}';
$adminLink = '{管理画面用初期ページへのリンク}';
$installMessage = '{インストール画面に表示するメッセージ}';
$author = '{プラグインの作成者名}';
$url = '{プラグイン作成者のホームページURL}';</syntaxhighlight>

## インストールスクリプトを準備する

インストールスクリプトは init.php というファイル名で以下のパスに設置します。<br /> このスクリプトは、PluginsController の admin_add メソッドより呼び出されます。

<pre>{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Config/init.php</pre>

インストール用の スキーマファイル、初期データファイルを登録するには、下記メソッドを呼び出します。

<syntaxhighlight lang="php">$this->Plugin->initDb('plugin', '{プラグイン名}');</syntaxhighlight>

<small>※ baserCMS３より引数が変更となっています。</small>

## バージョンファイルを準備する

プラグインのバージョンを示すバージョンファイルを次のパスに設置します。

<pre>{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/VERSION.txt</pre>

バージョン番号は、上記ファイルの１行目に記述します。<br /> baserCMSでは、３区切りまでの[バージョン番号][2]を認識します。

<pre>（例）1.2.3・・・{メジャーバージョン}.{マイナーバージョン}.{パッチ}</pre>

## プラグインイベント

baserCMSのプラグインは、本体に新しいコンテンツとしての機能を追加する以外に、本体の既にある機能の拡張を行ったり、振る舞いや表示内容を変えるという事も可能です。

本体機能の拡張を行うには、CakePHPの CakeEvent の拡張である[ BaserEvent ][3]を利用します。<br /> この機能は、コア本体が提供するイベントである の beforeFilter や、ヘルパーの afterLayout 等のイベントをプラグイン側から簡単に処理を割りこませる事ができます。

* [CakePHP イベントシステム][4]

これにより本体のビューが出力する内容を書き換えたり、baserCMSの管理システム内の編集画面に新しいフィールドを追加するという事ができるようになります。<br /> 例えば、Javascriptで各イベントに対し、イベントリスナーを利用してコールバック処理を登録する 事をイメージするとわかりやすいかもしれません。

処理を割りこませる為には、プラグインのフォルダ内に Event フォルダを作成し、そこにイベントリスナークラスを作成します。<br /> events プロパティにコールバックメソッド名を配列で定義し、同クラス内にコールバックメソッドを定義します。<br /> コールバックメソッド名は、events プロパティに登録したイベント名からドット（.）を除外した上でロウワーキャメルケースに変換した名称とします。<br /> プラグインのイベントの場合は、イベント名の最初にプラグイン名を付加します。

<pre>Mail.Mail.beforeSendEmail → mailMailBeforeSendEmail</pre>

### コントローラーイベントリスナ

コントローラーのイベントにコールバック処理を登録するには、下記のパスにクラスファイルを設置します。<br /> BcControllerEventListener を継承します。

<syntaxhighlight lang="php">
● {プラグイン名}ControllerEventListener
{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Event/{プラグイン名}ControllerEventListener.php

class PluginNameControllerEventListener extends BcControllerEventListener {
}
</syntaxhighlight>

### モデルイベントリスナ

モデルのイベントにコールバック処理を登録するには、下記のパスにクラスファイルを設置します。<br /> BcModelEventListener を継承します。

<syntaxhighlight lang="php">● {プラグイン名}ModelEventListener
{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Event/{プラグイン名}ModelEventListener.php

class PluginNameModelEventListener extends BcModelEventListener {
}</syntaxhighlight>

### ビューイベントリスナ

ビューのイベントにコールバック処理を登録するには、下記のパスにクラスファイルを設置します。<br /> BcViewEventListener を継承します。

<syntaxhighlight lang="php">● {プラグイン名}ViewEventListener
{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Event/{プラグイン名}ViewEventListener.php

class PluginNameViewEventListener extends BcViewEventListener {
}</syntaxhighlight>

### ヘルパイベントリスナ

ヘルパのイベントにコールバック処理を登録するには、下記のパスにクラスファイルを設置します。<br /> BcHelperEventListener を継承します。

<syntaxhighlight lang="php">● {プラグイン名}HelperEventListener
{baserCMSの設置フォルダ}/app/Plugin/{プラグイン名}/Event/{プラグイン名}HelperEventListener.php

class PluginNameHelperEventListener extends BcHelperEventListener {
}</syntaxhighlight>

## コールバックメソッド内でのデータの参照方法

コールバックメソッドでは、引数に CakeEvent を定義します。<br /> 引数名を $event とした場合、イベント固有のデータは、$event->data で参照する事ができます。<br /> また、イベントの発動元のオブジェクトを、$event->subject で参照する事ができます。

## 登録可能な本体のイベント

#### コントローラー

* {CakePHP標準イベント名}（例：beforeRender）
* {ControllerName}.{CakePHP標準イベント名}（例：Users.beforeRender）
* Mail.Mail.beforeSendEmail（メール送信直前）
* Mail.Mail.afterSendEmail（メール送信直後）
* Blog.BlogPosts.afterAdd （ブログ記事追加直後）
* Blog.BlogPosts.afterEdit（ブログ記事編集直後）
* Users.afterAdd（新規ユーザ追加直後）
* Users.afterEdit（既存ユーザ編集直後）
* Pages.afterAdd（新規ページ追加直後）
* Pages.afterEdit（既存ページ編集直後）

#### ビュー

* {CakePHPの標準イベント名}（例：beforeLayout）
* {ControllerName}.{CakePHPの標準イベント名}（例：Users.beforeLayout）
* beforeElement（エレメント生成直前）
* afterElement（エレメント生成直後）
* {ControllerName}.beforeElement（エレメント生成直前）
* {ControllerName}.afterElement（エレメント生成直後）
* header（ヘッダーエレメント生成直後）
* footer（フッターエレメント生成直後）
* {ControllerName}.header（ヘッダーエレメント生成直後）
* {ControllerName}.footer（フッターエレメント生成直後）

#### モデル

* {CakePHP標準イベント名}（例：beforeFind）
* {ModelName}.{CakePHP標準イベント名}（例：User.beforeFind）

#### ヘルパー

* Html.beforeGetLink（リンク取得直前）
* Html.afterGetLink（リンク取得直後）
* Form.beforeCreate（フォーム開始タグ生成直前）
* Form.afterCreate（フォーム開始タグ生成直後）
* Form.beforeEnd（フォーム終了タグ生成直前）
* Form.afterEnd（フォーム終了タグ生成直後）
* Form.beforeInput（フォームパーツタグ生成直前）
* Form.afterInput（フォームパーツタグ生成直後）
* Form.afterForm（メインフォーム生成直後）
* Form.afterOptionForm（オプションフォーム生成直後）

## プラグインイベントコード例

Sampleというプラグインで、コアのコントローラーのイベントにコールバックメソッドを登録します。

<syntaxhighlight lang="php">
/Sample/Event/SampleControllerEventListner.php

--
class SampleControllerEventListener extends BcControllerEventListener {
    // 登録先イベントの定義
    public $events = [
        'Users.beforeRender',
        'Users.afterEdit',
        'initialize'
    ];
    // ユーザーコントローラーにおいてレンダリング直前に呼び出される
    public function usersBeforeRender(CakeEvent $event) {
        // ビューにサンプルという文字列を引き渡す
        $Controller = $event->subject();
        $Controller->set('sample', 'sample');
    }
    // ユーザーコントローラーにおいてユーザー情報更新直後に呼び出される
    public function usersAfterEdit(CakeEvent $event) {
        // ユーザー情報変更後のデータを参照
        var_dump($event->data);
    }
    // ユーザーコントローラーにおいてアクションが実行される直前に呼び出される
    public function initialize(CakeEvent $event) {
        // サンプルヘルパーをコントローラーに追加
        $Controller = $event->subject();
        $Controller->helpers[] = 'Sample';
    }

}
</syntaxhighlight>

  [1]: http://book.cakephp.org/2.0/ja/plugins.html
  [2]: http://project.e-catchup.jp/projects/basercms/wiki/バージョン番号
  [3]: http://wiki.basercms.net/baserCMS%E3%81%AECakePHP%E6%8B%A1%E5%BC%B5%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6
  [4]: http://book.cakephp.org/2.0/ja/core-libraries/events.html


## プラグインのイベントを簡単に作成する

[http://lab.e-catchup.jp/catchup/cublank/tree/master blankプラグイン]を利用すると、プラグインのイベントを簡単に作成することができます。
[[Category:開発ガイド]]