Edit
Redmine Plugins

Redmineでは、いろいろな機能をプラグイン形式で提供できる仕組みになっている。そこで、ここでは簡単なプラグイン作成に挑戦してみる。

Edit
初期準備

# ruby script/rails generate redmine_plugin New_Plugin_Name

このスクリプトで plugins フォルダに New_Plugin_Name 名のフォルダが作成される。

Edit
インストール

# rake redmine:plugins:migrate RAILS_ENV=production

Edit
アンインストール

# rake redmine:plugins:migrate NAME=plugin_name VERSION=0 RAILS_ENV=production
# rm plugins/<Plugin_Name>

Edit
ソース構成のポイント

基本的には、rails のアプリ構成と同じ。但し redmine のプラグインとして特別に記述する部分がある。
また、Railsにおける詳しいファイル構成はここ

Edit
init.rb

Redmineのプラグイン設定画面に表示されるプラグイン情報をここで設定する。基本的に初期処理で自動作成される。

Edit
基本設定

Redmine::Plugin.register :New_Plugins_Name do                                    <- プラグイン名
   name 'Polls plugin'                                                                                <- 表示上の名前
   author 'John Smith'                                                                              <- 表示上の作者
   description 'A plugin for managing polls'                                              <- 表示上の概要
   version '0.0.1'                                                                                       <- 表示のバージョン
   url 'http://example.com/path/to/plugin'                                                <- 表示上のURL
   author_url 'http://example.com/about'                                                  <- 表示上の作者のURL
end

Edit
TOPページのメニューにタブを追加

この init.rb に下記の設定を入れることで、タブに項目を入れることができる。

Redmine::Plugin.register :redmine_New_Plugin_Name do                                                               <- これは元から init.rb に存在する。
   menu :top_menu, :New_Plugin_Name, { :controller => 'New_Plugin_Namenction', :action => 'index' }, :caption => 'メニュー項目名'  <- これを追加
end

メニューの種類

引数メニューの種類の説明
:top_menuページ一番左上のプロジェクトの右(ヘルプの左)
:account_menuページ一番右上のログインボタン等の右端
:application_menuプロジェクトを選択していない画面。ホームやマイページなどの場合のアプリメニューの一番右に追加
:project_menuプロジェクトを選択している場合のアプリメニューの一番右。通常はWiki などの右側。プロジェクトメニューにする場合には、オプション指定の param を忘れないこと。
:admin_menu管理者向けの管理画面のメニューに追加。通常はLDAP認証とプラグインの間

オプションの種類

引数オプションの説明
:captionメニューに表示する文字。文字の直接指定のほか、多言語用のキーワード、プロジェクトからの文字取得などの方法を指定できる。
:paramパラメータとしてプロジェクトIDを指定できる。ちなみにこのオプションを指定することで、コントローラでは、@project = Project.find(params[:project_id]) という形でプロジェクトを取得することができる。例 :param => :project_id
:before, :afterメニューのどこに新メニュー項目を追加するか指定できる。例 :after => :activity
:ifa Proc that is called before rendering the item, the item is displayed only if it returns true
:first, :lastif set to true, the item will stay at the beginning/end of the menu (eg. :last => true)
:htmla hash of html options that are passed to link_to when rendering the menu item

Edit
パーミッション設定の追加

追加するプラグインの機能に対するパーミッション設定をさせる場合にはここを参照

 permission :PluginNames, { :PluginNames => [:index, :vote] }, :public => true

上記は、TOPメニュー等の場合のパーミッション指定方法(public => true で無条件表示)

 project_module :PluginNames do
   permission :view_PluginNames, :Plugin_Names => :index
   permission :vote_PluginNames, :Plugin_Names => :vote
 end

上記は、プロジェクト単位の場合のパーミッション指定方法。

Edit
プラグイン別の設定画面

<プラグインの設定リンクの表示>

Redmine::Plugin.register :PluginNames do                                    <- プラグイン名
   settings :default => {'empty' => true}, :partial => 'settings/PluginNames'
end

設定リンクが押されると、特定のviewファイルが呼び出される。(実際にはredmine本体にこのファイルが追加されるイメージ)

# vi <プラグインフォルダ>/app/views/settings/_PluginNames.html.erb

サンプル

<table>
  <tbody>
    <tr>
      <th>Notification Default Address</th>
      <td><input type="text" id="settings_notification_default" 
                     value="<%= settings['notification_default'] %>" 
             name="settings[notification_default]" >
    </tr>
  </tbody>
</table>

Edit
db/seeds.rbは機能しない。

プラグインでは、通常のrailsのdb/seeds.rb を利用した、初期データの設定ができないため、この init.rb の中に記述する。但し、redmine:pluins:migrate を行うたびに次々とレコードが追加されてしまうため、一度 migrate したら、コメントアウトするようにした方が良い。

Edit
config/routes.rb

Redmine本体と同じように、プラグインフォルダ下の config/routes.rb にプラグインの routes を設定することでプラグインの route を解決する。

Edit
データモデル作成

# ruby script/rails generate redmine_plugin_model <plugin_name> <model_name> [field[:type][:index] field[:type][:index] ...]
appアプリケーションを格納するディレクトリ。主要なプログラムはこの配下に格納
dbデータベースの設定ファイルを格納するディレクトリ
db/migrateデータベースの設定ファイルを格納するディレクトリ。※マイグレーションとは直接SQLを使わずに、データベースのテーブルやカラムなどの構造を変更できる仕組み
testアプリケーションのテストに使うファイルを格納するディレクトリ

モデルを作成すると、dbフォルダにモデルのレイアウトと、appフォルダにアプリ用のソースが作成される。

Edit
スタイルシートの読込

プラグインで追加された、view画面に以下の行を追加するとプラグイン用に準備した、スタイルシートが読み込まれる。

<% content_for :header_tags do %>
   <%= stylesheet_link_tag 'TagName', :plugin => 'redmine_PluginNames' %>
<% end %>

CSSファイルを置いておく場所は、プラグインフォルダの下の、assets/stylesheets に配置する。

# vi assets/stylesheets/TagName.css
  a.vote { font-size: 120%; }
  a.vote.yes { color: green; }
  a.vote.no  { color: red; }

<Viewのヘッダー定義>

<% html_title "HTML表示名称" -%>

Edit
HOOK機能

plugin では、既存のRedmineの画面にボタンや表示を追加したい場合などがある。その場合では元のソースを改変することなく、plugin フォルダ内にHOOK用の要素を追加するだけで既存画面に追加でき、plugin の導入を容易くしている。

フォルダ概要
app/viewsプラグインで新規で追加される画面
app/views/hooksRedmine側の画面に追加される要素のView記述をしたもの
lib/<PluginName>/hook.rbフックされたビューのコントローラ機能

Edit
便利なプラグイン紹介

Edit
Custom CSS

Redmineのスタイルをファイル読込を必要とせず、その場で修正できる。

<設定例:h2のスタイル変更>

h2 {
  border-bottom:1px solid #CCCCCC;
  border-left:8px solid #202060;
  padding:3px 3px 3px 10px;
}

Edit
TIP&トラブルシューティング

Edit
database configuration does not specify adapterというエラー

これはDBアクセスする際の設定が読み込めないというエラー。ようするに、config/database.yml のどれを使っていいのか不明ということ。よって、

# export RAILS_ENV=production

という形のように、database アクセス定義を rails に伝える。

Edit
Multiple migrations have the name xxxxx というのがでる。

db/migrate/ の下に、同じモデルのバージョン番号違いが存在する。古い方のファイルを削除する。