Project

General

Profile

プラグイン チュートリアル » History » Version 16

Haru Iida, 05/31/2009 03:12 PM

1 1 Haru Iida
www.redmine.orgの"Plugin Turorial":http://www.redmine.org/wiki/redmine/Plugin_Tutorial を和訳してみます。
2
3
h1. プラグイン チュートリアル
4
5 6 Haru Iida
注意: このチュートリアルはRedmineの開発リビジョン @r1786@ 以上を対象にしています。
6 1 Haru Iida
7
{{toc}}
8
9
h2. 新しいプラグインを作る。
10
11
プラグインの新規作成はRedmineのプラグインジェネレータを使用して行うことができます。
12
ジェネレータのコマンドは以下です。:
13
14
<pre>ruby script/generate redmine_plugin <plugin_name></pre>
15
16
コマンドプロンプトを開き "cd" であなたがredmineをインストールしたディレクトリに移動し、以下のコマンドを実行してみましょう。:
17
18
  % ruby script/generate redmine_plugin Polls
19
20 2 Haru Iida
@vendor/plugins/redmine_polls@ の下に以下のようなファイルとディレクトリが作られます:
21 1 Haru Iida
22
<pre>
23
      create  vendor/plugins/redmine_polls/app/controllers
24
      create  vendor/plugins/redmine_polls/app/helpers
25
      create  vendor/plugins/redmine_polls/app/models
26
      create  vendor/plugins/redmine_polls/app/views
27
      create  vendor/plugins/redmine_polls/db/migrate
28
      create  vendor/plugins/redmine_polls/lib/tasks
29
      create  vendor/plugins/redmine_polls/assets/images
30
      create  vendor/plugins/redmine_polls/assets/javascripts
31
      create  vendor/plugins/redmine_polls/assets/stylesheets
32
      create  vendor/plugins/redmine_polls/lang
33
      create  vendor/plugins/redmine_polls/README
34
      create  vendor/plugins/redmine_polls/init.rb
35
      create  vendor/plugins/redmine_polls/lang/en.yml
36
</pre>
37
38 2 Haru Iida
@vendor/plugins/redmine_polls/init.rb@ を編集してあなたのプラグインの情報を書き込んでください。(name, author, description および version):
39 1 Haru Iida
40
<pre><code class="ruby">
41
require 'redmine'
42
43
Redmine::Plugin.register :redmine_polls do
44
  name 'Polls plugin'
45
  author 'John Smith'
46
  description 'A plugin for managing polls'
47
  version '0.0.1'
48
end
49
</code></pre>
50
51 2 Haru Iida
そしてRedmineを起動し、ブラウザから次のアドレスを入力します。http://localhost:3000/admin/info.
52
ログイン後、あなたのプラグインがプラグイン一覧に加わっていることが確認できます。
53 1 Haru Iida
54 4 Haru Iida
!plugins_list1.png!
55 1 Haru Iida
56 5 Haru Iida
h2. モデルを作る
57 1 Haru Iida
58 5 Haru Iida
それではこのプラグインのモデルとして Poll を作ってみましょう。:
59 1 Haru Iida
60
  ruby script/generate redmine_plugin_model polls poll question:string yes:integer no:integer
61
62 5 Haru Iida
このコマンドで Poll モデルおよびPollモデルに対応したマイグレーションファイルが作成されます。
63
(訳注:マイグレーションファイルとは、RedmineのDBにこのモデル用のテーブルを作成するためのスクリプトファイルです)
64 1 Haru Iida
65 5 Haru Iida
ここで注意が必要です。timestamped migrationは今のRedmineプラグインエンジンではサポートされていません。ファイル名についているタイムスタンプを"001", "002"のような名前に変更してください。
66 1 Haru Iida
67 5 Haru Iida
実際にデータベースへのマイグレーションを行うためには以下のコマンドを実行します。:
68 1 Haru Iida
69
  rake db:migrate_plugins
70
71 5 Haru Iida
すべてのプラグインはそれぞれに自身のマイグレーションファイルを持っています。
72 1 Haru Iida
73 6 Haru Iida
それではconsoleスクリプトからPollのデータを追加してみましょう。ちゃんとテーブルが作られていることを確認できます。consoleを使用すると対話的にRedmineを動かして確認できます。また、遊びながらいろいろな情報を得ることができます。それでは2つのPollオブジェクトを作ります。
74 1 Haru Iida
75
<pre>
76
script/console
77
>> Poll.create(:question => "Can you see this poll ?")
78
>> Poll.create(:question => "And can you see this other poll ?")
79
>> exit
80
</pre>
81
82 6 Haru Iida
プラグインディレクトリの @vendor/plugins/redmine_polls/app/models/poll.rb@ を編集して #vote メソッドを追加しましょう。このメソッドはコントローラから実行されるものです。:
83 1 Haru Iida
84
<pre><code class="ruby">
85
class Poll < ActiveRecord::Base
86
  def vote(answer)
87
    increment(answer == 'yes' ? :yes : :no)
88
  end
89
end
90
</code></pre>
91
92 7 Haru Iida
h2. コントローラを作成する。
93 1 Haru Iida
94 7 Haru Iida
この段階ではまだこのプラグインは何もすることができません。このプラグインにコントローラを追加してみましょう。コントローラの作成にはプラグインコントローラジェネレータを使用できます。文法は以下です。:
95 1 Haru Iida
96
<pre>ruby script/generate redmine_plugin_controller <plugin_name> <controller_name> [<actions>]</pre>
97
98 7 Haru Iida
ではコマンドプロンプトから以下のように打ってみましょう。:
99 1 Haru Iida
100
<pre>
101
% ruby script/generate redmine_plugin_controller Polls polls index vote
102
      exists  app/controllers/
103
      exists  app/helpers/
104
      create  app/views/polls
105
      create  test/functional/
106
      create  app/controllers/polls_controller.rb
107
      create  test/functional/polls_controller_test.rb
108
      create  app/helpers/polls_helper.rb
109
      create  app/views/polls/index.html.erb
110
      create  app/views/polls/vote.html.erb
111
</pre>
112
113 7 Haru Iida
コントローラ @PollsController@ と2つのアクション (@#index@ and @#vote@) が作成されます。
114 1 Haru Iida
115 7 Haru Iida
@vendor/plugins/redmine_polls/app/controllers/polls_controller.rb@ を編集して 2つのアクションを実装します。
116 1 Haru Iida
117
<pre><code class="ruby">
118
class PollsController < ApplicationController
119
  unloadable
120
121
  def index
122
    @polls = Poll.find(:all)
123
  end
124
125
  def vote
126
    poll = Poll.find(params[:id])
127
    poll.vote(params[:answer])
128
    if poll.save
129
      flash[:notice] = 'Vote saved.'
130
      redirect_to :action => 'index'
131
    end
132
  end
133
end
134
</code></pre>
135
136 8 Haru Iida
そして @vendor/plugins/redmine_polls/app/views/polls/index.html.erb@ を編集すると先ほど作成した2つのpollを表示できます。:
137 1 Haru Iida
138
139
<pre>
140
<h2>Polls</h2>
141
142
<% @polls.each do |poll| %>
143
  <p>
144
  <%= poll[:question] %>?
145
  <%= link_to 'Yes', {:action => 'vote', :id => poll[:id], :answer => 'yes'}, :method => :post %> (<%= poll[:yes] %>) /
146
  <%= link_to 'No', {:action => 'vote', :id => poll[:id], :answer => 'no'}, :method => :post %> (<%= poll[:no] %>)
147
  </p>
148
<% end %>
149
</pre>
150
151 8 Haru Iida
@vendor/plugins/redmine_polls/app/views/polls/vote.html.erb@ は対応するactionから使われることがないので削除してよいです。
152 1 Haru Iida
153 8 Haru Iida
さあ、Redmineを再起動してブラウザから http://localhost:3000/polls にアクセスしましょう。
154
2つのpollが確認でき、それらに投票することができるでしょう。:
155 1 Haru Iida
156 8 Haru Iida
!pools1.png!
157 1 Haru Iida
158
Note that poll results are reset on each request if you don't run the application in production mode, since our poll "model" is stored in a class variable in this example.
159
160 9 Haru Iida
h2. メニューを拡張する。
161 1 Haru Iida
162 9 Haru Iida
コントローラは動くようになりましたが、このままではユーザはURLを知らない限り投票画面を見ることができません。RedmineのプラグインAPIを使用するとメニューを拡張できます。アプリケーションメニューに新しい項目を追加してみましょう。
163 1 Haru Iida
164 9 Haru Iida
h3. アプリケーションメニューを拡張する。
165 1 Haru Iida
166 9 Haru Iida
@vendor/plugins/redmine_polls/init.rb@ を編集してplugin registration blockの最後に以下の行を追加してください。:
167 1 Haru Iida
168
<pre><code class="ruby">
169
Redmine::Plugin.register :redmine_polls do
170
  [...]
171
  
172
  menu :application_menu, :polls, { :controller => 'polls', :action => 'index' }, :caption => 'Polls'
173
end
174
</code></pre>
175
176 9 Haru Iida
文法は以下です。:
177 1 Haru Iida
178
  menu(menu_name, item_name, url, options={})
179
180 9 Haru Iida
拡張できるメニューは4種類です。:
181 1 Haru Iida
182 9 Haru Iida
* @:top_menu@ - 最上部の左側のメニュー。
183
* @:account_menu@ - 最上部の右側のメニュー。ログイン/ログアウトがある。
184
* @:application_menu@ - プロジェクトの外でのメインメニュー。
185
* @:project_menu@ - プロジェクト内でのメインメニュー。
186 1 Haru Iida
187 9 Haru Iida
以下のオプションが使えます。:
188 1 Haru Iida
189 9 Haru Iida
* @:param@ - プロジェクトIDを渡すのに用いられる変数のキー。 (デフォルトは @:id@)
190
* @:if@ - メニュー項目のレンダリング前に呼ばれるProc。メニュー項目はこのProcの戻りがtrueの場合にのみ表示される。
191
* @:caption@ - メニューのキャプション。以下が使えます。:
192 1 Haru Iida
193 9 Haru Iida
  * ローカライズ文字列用シンボル
194
  * 文字列
195
  * projectを引数としたProc
196 1 Haru Iida
197 9 Haru Iida
* @:before@, @:after@ - メニューを挿入する場所の指定 (例 @:after => :activity@ 訳注:「活動」ページの後ろに挿入される)
198
* @:last@ - trueに設定するとメニューの最後に追加される。 (例 @:last => true@)
199
* @:html_options@ - html オプションのHash。メニュー表示時の @link_to@ に渡される。訳注: @link_to@はRailsのAPI
200 1 Haru Iida
201 9 Haru Iida
今回の例ではメニュー項目をアプリケーションメニューに追加します。アプリケーションメニューはデフォルトでは空です。
202
Redmineを再起動して http://localhost:3000 にアクセスしてみましょう。:
203 1 Haru Iida
204 9 Haru Iida
!application_menu.png!
205 1 Haru Iida
206 9 Haru Iida
ようこそ画面のPollsタブをクリックして投票画面に行けるはずです。
207 1 Haru Iida
208 10 Haru Iida
h3. プロジェクトメニューを拡張する。
209 1 Haru Iida
210 10 Haru Iida
さあ、今度はpollsをプロジェクト用プラグインとした場合の例です。(今回のpollモデルはそう設計されてませんが)。Pollsタブをプロジェクトメニューに追加しましょう。
211
@init.rb@ を開いて先ほど追加した行を以下の2行に書き換えてください。:
212 1 Haru Iida
213
<pre><code class="ruby">
214
Redmine::Plugin.register :redmine_polls do
215
  [...]
216
217
  permission :polls, {:polls => [:index, :vote]}, :public => true
218
  menu :project_menu, :polls, { :controller => 'polls', :action => 'index' }, :caption => 'Polls', :after => :activity, :param => :project_id
219
end
220
</code></pre>
221
222 10 Haru Iida
2行目がプロジェクトメニューにPollsタブを追加する定義です。活動タブのすぐ後ろに追加します。
223
最初の行は @PollsController@ の2つのアクションをpulicにするための設定です。詳細については後ほど説明します。
224 1 Haru Iida
225 10 Haru Iida
Redmineを再起動し、プロジェクトを表示します。:
226 1 Haru Iida
227 11 Haru Iida
!project_menu.png!
228 1 Haru Iida
229 12 Haru Iida
Pollsタブをクリックしてください。プロジェクトメニューが消えてしまうことに気付きましたか?
230
プロジェクトメニューを表示しておくためにはコントローラのインスタンス変数 @@project@ を設定してあげる必要があります。
231 1 Haru Iida
232 12 Haru Iida
PollsController を以下のように編集します。:
233 1 Haru Iida
234
<pre><code class="ruby">
235
def index
236
  @project = Project.find(params[:project_id])
237
  @polls = Poll.find(:all) # @project.polls
238
end
239
</code></pre>
240
241 12 Haru Iida
プロジェクトIDはparamの中の @:project_id@ に格納されています。なぜなら先ほどのメニューの定義で @:param => :project_id@ と設定したからです。
242 1 Haru Iida
243 12 Haru Iida
さあ、これでPollsタブをクリックしてもプロジェクトメニューが消えなくなりました。:
244 1 Haru Iida
245 13 Haru Iida
!project_menu_pools.png!
246 1 Haru Iida
247 13 Haru Iida
h2. パーミッションを定義する。
248 1 Haru Iida
249 14 Haru Iida
この状態ではすべての人が投票を行うことができます。ではパーミッションの定義をしてみましょう。
250
ここでは2種類のプロジェクトベースのパーミッションを定義します。ひとつはpollsの表示に関するもの、もう一つは投票に関するものです。これを行うと、パーミッションはpublicでは無くなります。(@:public => true@ オプションは削除します).
251 1 Haru Iida
252 14 Haru Iida
@vendor/plugins/redmine_polls/init.rb@ を編集して先ほどのパーミッション定義を以下の2行に置き換えます。:
253 1 Haru Iida
254
<pre><code class="ruby">
255
256
  permission :view_polls, :polls => :index
257
  permission :vote_polls, :polls => :vote
258
</code></pre>
259
260
261 14 Haru Iida
Redmineを再起動して次のURLにアクセスしてみましょう。 http://localhost:3000/roles/report:
262 1 Haru Iida
263 15 Haru Iida
!permissions1.png!
264 1 Haru Iida
265 14 Haru Iida
これで既存のロールに対してパーミッションを設定できるようになりました。
266 1 Haru Iida
267 14 Haru Iida
もちろん、パーミッションに応じてユーザのアクセス制御を行うためにはPollsControllerにコードを追加する必要があります。
268 1 Haru Iida
269 14 Haru Iida
今回の場合は @:authorize@ フィルターを追加すること、およびこのフィルターが呼ばれる前に必ず @project に値がセットされるようにするだけです。
270
271
@#index@ アクションでは以下のようにします。:
272 1 Haru Iida
273
<pre><code class="ruby">
274
class PollsController < ApplicationController
275
  unloadable
276
  
277
  before_filter :find_project, :authorize, :only => :index
278
279
  [...]
280
  
281
  def index
282
    @polls = Poll.find(:all) # @project.polls
283
  end
284
285
  [...]
286
  
287
  private
288
  
289
  def find_project
290
    # @project variable must be set before calling the authorize filter
291
    @project = Project.find(params[:project_id])
292
  end
293
end
294
</code></pre>
295
296 16 Haru Iida
@#vote@ アクションが動く前に現在のプロジェクトを取得します。これを行うと、投票は管理者もしくはこのプロジェクトの許可されたロールのユーザ以外行えなくなります。
297 1 Haru Iida
298
299 16 Haru Iida
h2. プロジェクトモジュールを作る。
300 1 Haru Iida
301 16 Haru Iida
今現在、pollの機能はすべてのプロジェクトに追加されています。しかし、pollsを限られたプロジェクトのみに使わせたい場合もあるでしょう。
302
ここでは 'Polls' プロジェクトモジュールを作成します. これはパーミッション定義を @#project_module@ 定義で囲むことによって実現します。
303 1 Haru Iida
304 16 Haru Iida
@init.rb@ を編集してパーミッションの定義を変更します。:
305
306 1 Haru Iida
<pre><code class="ruby">
307
  project_module :polls do
308
    permission :view_polls, :polls => :index
309
    permission :vote_polls, :polls => :vote
310
  end
311
</code></pre>
312
313 16 Haru Iida
Redmineを再起動し、適当なプロジェクトの設定メニューを開きます。そしてモジュールタブをクリックします。するとモジュールリストの最後にPolls moduleがあることが確認できます。 (デフォルトではチェックはついていません):
314 1 Haru Iida
315 16 Haru Iida
!modules.png!
316 1 Haru Iida
317
You can now enable/disable polls at project level.
318
319
h2. Improving the plugin views
320
321
h3. Adding stylesheets
322
323
Let's start by adding a stylesheet to our plugin views.
324
Create a file named @voting.css@ in the @vendor/plugins/redmine_polls/assets/stylesheets@ directory:
325
326
<pre>
327
a.vote { font-size: 120%; }
328
a.vote.yes { color: green; }
329
a.vote.no  { color: red; }
330
</pre>
331
332
When starting the application, plugin assets are automatically copied to @public/plugin_assets/redmine_polls/@ by Rails Engines to make them available through your web server. So any change to your plugin stylesheets or javascripts needs an application restart.
333
334
Then, append the following lines at the end of @vendor/plugins/redmine_polls/app/views/polls/index.html.erb@ so that your stylesheet get included in the page header by Redmine:
335
336
<pre>
337
<% content_for :header_tags do %>
338
    <%= stylesheet_link_tag 'voting', :plugin => 'redmine_polls' %>
339
<% end %>
340
</pre>
341
342
Note that the @:plugin => 'redmine_polls'@ option is required when calling the @stylesheet_link_tag@ helper.
343
344
Javascripts can be included in plugin views using the @javascript_include_tag@ helper in the same way.
345
346
h3. Setting page title
347
348
You can set the HTML title from inside your views by using the @html_title@ helper.
349
Example:
350
351
  <% html_title "Polls" -%>