r-labs

h1. プラグインのスケルトン作成

前置きが長くなりましたが、いよいよプラグインの実装を行っていきましょう。

h2. プラグイン名前を決める

最初にプラグインの名前を決める必要があります。

サンプルなので何でもいいのですが、標準的なものということで *Redmine Standard* にしましょう。

今回のチュートリアルでは簡単なものですが、このサンプルに今後フィルタや wiki などの機能を付けてもっと標準的なものにしたいと考えています。それでこの標準サンプルを少し変更するだけでちょっとしたプラグインが作れるようにできたらいいなと思っています。

h2. スケルトン

Rails はフレームワークでその枠組みにあわせてアプリを作成する必要があります。 Rails ではこの枠組みにあったアプリを作りやすいようにスケルトン(雛形)を生成する機能があります。生成したスケルトンの中身を書き込んで実装することによってフレームワークにあったものとなります。

Redmine でも同様にプラグイン用のスケルトンを生成する機能があります。

h2. スケルトン作成コマンドの実行

それでは実際にスケルトンを生成してみましょう。

Redmine のトップディレクトリに移動して、生成コマンドを実行します。

<pre>

$ ruby script/rails redmine_plugin プラグイン名

</pre>

プラグイン名を Redmine Standard にしたので、実際のコマンドは以下のようになります。

<pre>

$ ruby script/rails generate redmine_plugin redmine_standard

</pre>

ファイル名にする場合は Pascal ケースをスネークケースにするという決まりがありました。

そのため Redmine Standard の大文字で形式を redmine_standard と小文字形式で指定しています。

RedmineStandardと大文字のまま指定も可能ですが、後で述べるコントローラのスケルトン生成時にファイル名がスネークケースにならない場合があるので推奨しません。

実行結果

<pre>

      create  plugins/redmine_standard/app

      create  plugins/redmine_standard/app/controllers

      create  plugins/redmine_standard/app/helpers

      create  plugins/redmine_standard/app/models

      create  plugins/redmine_standard/app/views

      create  plugins/redmine_standard/db/migrate

      create  plugins/redmine_standard/lib/tasks

      create  plugins/redmine_standard/assets/images

      create  plugins/redmine_standard/assets/javascripts

      create  plugins/redmine_standard/assets/stylesheets

      create  plugins/redmine_standard/config/locales

      create  plugins/redmine_standard/test

      create  plugins/redmine_standard/test/fixtures

      create  plugins/redmine_standard/test/unit

      create  plugins/redmine_standard/test/functional

      create  plugins/redmine_standard/test/integration

      create  plugins/redmine_standard/README.rdoc

      create  plugins/redmine_standard/init.rb

      create  plugins/redmine_standard/config/routes.rb

      create  plugins/redmine_standard/config/locales/en.yml

      create  plugins/redmine_standard/test/test_helper.rb

</pre>

コマンドを実行すると @plugins/redmine_standard@ 以下にスケルトンが生成されます。

Rails の概要のところでも説明しましたが、 @plugins@ 以下の各ディレクトリがプラグインとして扱われます。ここにスケルトンが生成されたことになります。

あと プラグインの名称を先頭に redmine_ と付く形の名称にしましたが、これは Redmine 1.x のプラグインスケルトン生成ルールを踏襲した形にしてあります。命名規則として必須のものではありません。

h2. プラグインのディレクトリ構成

生成されたプラグインの構成をみていきましょう。

<pre>

init.rb

app/

├ controllers/

├ helpers/

├ models/

└ views/

db/migrate/

lib/

assets/

├ images/

├ javascripts/

└ stylesheets/

config

├ locales/

└ routes.rb

test/

├ fixtures/

├ unit/

├ functional/

├ integration/

└ test_helper.rb

README.rdoc

</pre>

*init.rb* はプラグインで一番最初にロードされるファイルです。ここにプラグインの基本情報を書いていきます。これは[[GuideInitRb|次章]]で説明します。

*app* にはプラグインの主な中身を記述することになります。 *controllers*, *views*, *models* のそれぞれがそのまま MVC 構造の対応する部分を格納するディレクトリです。helpers はライブラリのようによく使われる共通的な処理を格納する場所になります。helpers を除いた 3 つの部分がプラグインの主要な部分ですので、これから一つづつ説明していきます。

lib も共通処理のファイルを置くところです。プラグイン中で未定義のクラス(FooBar)を使うと、スネークケースに変更して(foo_bar.rb)、そのファイルをロードしますが、その検索場所がこの lib です。

lib も app/helpers も同じような用途のものを格納しますが、大きな違いは development モードでの動作が変わってきます。 development モードでは redmine の再起動なしで変更が反映されますが、それは app 以下のものだけです。 init.rb や lib 以下の変更は redmine の再起動が必要となります。

だったら、全部 app/helpers に書けば、ということになるかと思いますが、 helpers は app の他の部分からしか呼び出せないので、 init.rb から呼び出したいものは lib に書く必要があります(私がやり方を知らないだけかもしれませんが)。また、自分で作成したクラスなども lib に書きます。

(init.rb から呼び出しができるようにする方法がありました。 "プラグイン開発記 - init.rb から Helper メソッドの呼び出し":http://yohshiy.blog.fc2.com/blog-entry-13.html )

*db/migrate/* はデータベースの操作する処理を記述します。ここは model とあわせて説明します。

assets/ にはそれぞれプラグイン独自に作成した 画像、 JavaScript, スタイルシート(CSS) をそれぞれ格納します。こちらの使用はちょっと応用的な内容ですので、 [[TipsOriginalImage|プラグイン Tips]] の説明を見てください。

*config/locales* は国際化のためにそれぞれの言語ごとのラベルやメッセージなどをおきます。こちらは [[GuideI18n|国際化]] のところで説明します。

test/ には、テストコードを記述します。 test も重要ですが、なくても作れるのでテストについては説明は書いてません。単に私がよく知らないので書けないというだけですが。

README.rdoc にはプラグインのインストール方法などの説明を書いておきます。よくオープンソースのアプリケーションには readme.txt のようなファイルがあると思いますが、そういったものになります。

rdoc というのは wiki のようなフォーマットで書く ruby のドキュメントで、これを元に html ファイルを生成できたりします。また、Rails のトップディレクトリで以下のコマンド実行すると各プラグインのソースコードを解析してドキュメントを生成してくれます。 Doxygen の Ruby 版のようなものです。

<pre>

$ rake doc:plugins

</pre>

しかし、rdoc で書いていなければ動かないということはないので、気にせず自由に書いてもかまわないと思います。私も最近は README.rwiki という名前で wiki 形式で書いて、それをサイトなどにすぐ貼り付けられるようにしています。

---

| [[プラグイン開発ガイド|^]] | [[GuideSampleSpec|<<]] | [[GuideInitRb|>>]] |