GuideForProject » 履歴 » バージョン 8
NAITOH Jun, 2013/03/06 23:47
Redmine 2.x対応の記載に更新
1 | 1 | Mitsuyoshi Yoshida | h1. プロジェクトで利用可能にする |
---|---|---|---|
2 | |||
3 | プラグインをプロジェクトごとに使用できるようするためにはプロジェクトモジュールとしての登録とプロジェクトメニューへの項目の追加が必要となります。 |
||
4 | |||
5 | |||
6 | h2. モジュールと permission の設定 |
||
7 | |||
8 | モジュールの登録ではモジュール名とアクションごとの実行する権限(permission)を指定します。 |
||
9 | |||
10 | |_. 権限 |_. アクション | |
||
11 | 8 | NAITOH Jun | | データの表示 | index, view, preview | |
12 | 1 | Mitsuyoshi Yoshida | | データの管理 | new, edit, destory | |
13 | |||
14 | 8 | NAITOH Jun | 権限の指定は init.rb の Redmine::Plugin.register メソッドで行います。次の記述をブロック内に追加してください。 |
15 | 1 | Mitsuyoshi Yoshida | |
16 | <pre><code class="ruby"> |
||
17 | project_module :standard do |
||
18 | 8 | NAITOH Jun | permission :view_foos, :foos => [:index, :show, :preview] |
19 | 1 | Mitsuyoshi Yoshida | permission :manage_foos, :foos => [:new, :edit, :destroy], |
20 | :require => :member |
||
21 | end |
||
22 | </code></pre> |
||
23 | |||
24 | *project_module* メソッドの引数でモジュール名(standard)を指定し、ブロック内で *permission* メソッドを呼び出して権限の指定をしています。 |
||
25 | |||
26 | permission メソッドの書式は次の形です。 |
||
27 | |||
28 | <pre><code class="ruby"> |
||
29 | permission(name, hash, options={}) |
||
30 | </code></pre> |
||
31 | |||
32 | 第一引数で権限の名前を指定します。 |
||
33 | 第二引数にはコントローラ名をキー、アクション名の配列を値としたハッシュを渡します。サンプルではコントローラは一つしかありませんが、複数あることもあるので、ハッシュで指定できるようになっています。 |
||
34 | 第三引数はオプションです。 |
||
35 | |||
36 | Rails では次のようなスタイルがよくとられるので慣れておきましょう。 |
||
37 | 2 | Mitsuyoshi Yoshida | |
38 | 1 | Mitsuyoshi Yoshida | * メソッドのオプション的な指定は最後の引数でシンボル名をキーとしたハッシュを使ってまとめて渡す |
39 | 3 | Mitsuyoshi Yoshida | * ハッシュが一つのペアしか持たなかったり、最後の引数などで括弧 {} が省略できる場合は省略する |
40 | 1 | Mitsuyoshi Yoshida | |
41 | このオプションの *:require* の指定を使って、データ管理の権限(:manage_foos)ではプロジェクトメンバー以外の Non member や Anonymous(ログインしていない人)では使えないようにしています。 |
||
42 | |||
43 | それでは Redmine を起動して、プラグインをプロジェクトで使用できるようにしましょう。 |
||
44 | |||
45 | まず、管理メニューにあるロールと権限の *権限レポート* でチェックをいれて権限を与えます。 |
||
46 | |||
47 | !permission.png! |
||
48 | |||
49 | 次にプラグインを使いたいプロジェクトの設定で Standard モジュールを有効にします。 |
||
50 | |||
51 | !module_add.png! |
||
52 | |||
53 | このときの表示は指定したモジュール名などがほぼそのまま表示されているだけですが、これを日本語に変更する方法は[[GuideI18n|国際化]]のところで説明します。 |
||
54 | |||
55 | |||
56 | h2. プラグインメニューへの追加 |
||
57 | |||
58 | プロジェクトでモジュールを有効にしてもまだ何も変わりません。実際にこのプラグインを使えるようにするためにはプロジェクトメニューに項目を追加する必要があります。 |
||
59 | プロジェクトメニューにはこのプラグインで最初に表示させたいページに対応するアクションを追加します。サンプルでは foos コントロールの index アクションとなります。 |
||
60 | |||
61 | メニュー項目の追加も init.rb で行います。先ほどの記述の後に以下を加えます。 |
||
62 | |||
63 | <pre><code class="ruby"> |
||
64 | 6 | Mitsuyoshi Yoshida | menu :project_menu, :standard, { :controller => 'foos', :action => 'index'}, :param => :project_id |
65 | 1 | Mitsuyoshi Yoshida | </code></pre> |
66 | |||
67 | メニューの項目の追加は *menu* メソッドを使います。 |
||
68 | |||
69 | <pre><code class="ruby"> |
||
70 | menu(menu, item, url, options={}) |
||
71 | </code></pre> |
||
72 | |||
73 | 第 1 引数はメニューの名前です。ここではプロジェクトメニューを指定します。指定できるメニューは [[GuideSampleSpec|サンプル仕様]] で説明した 4 つです。 |
||
74 | |||
75 | |_. メニュー |_. メニュー名 | |
||
76 | | トップメニュー | :top_menu | |
||
77 | | アカウントメニュー | :account_menu | |
||
78 | | プロジェクトメニュー | :project_menu | |
||
79 | | アプリケーションメニュー | :application_menu | |
||
80 | |||
81 | 第 2 引数はメニューの項目名です。 |
||
82 | 第 3 引数はメニューをクリックしたときのリンク先の URL を指定します。 |
||
83 | 6 | Mitsuyoshi Yoshida | 第 4 引数はオプションです。ここでは :param オプションで *:project_id* のキーに *プロジェクト識別名* を割り当てています。 |
84 | 1 | Mitsuyoshi Yoshida | |
85 | |||
86 | 6 | Mitsuyoshi Yoshida | h2. URL の指定方法 |
87 | 1 | Mitsuyoshi Yoshida | |
88 | 前節のメニューで行った URL の指定方法は *link_to* などでの他の Rails のリンクの指定方法と同じです。 |
||
89 | URL の指定方法についてもう少し詳しく説明しましょう。 |
||
90 | |||
91 | 6 | Mitsuyoshi Yoshida | |
92 | h2. Rails の機能 |
||
93 | |||
94 | 1 | Mitsuyoshi Yoshida | URL として文字列を指定すると単純にその文字列が url として使用されますが、ハッシュで指定するとそれを元に URL を生成します。 |
95 | |||
96 | 指定するキーはコントローラ名(:controller)、アクション名(:action)と ID名(:id) で、そのキーの値を使って次のようなアドレスとなります。 |
||
97 | |||
98 | <pre> |
||
99 | サーバアドレス/コントローラ名/アクション名/ID名 |
||
100 | </pre> |
||
101 | |||
102 | 6 | Mitsuyoshi Yoshida | ID 名は省略可能で省略されると ID 名の部分はなくなります。 |
103 | param で追加された値は http の GET メソッドによる引数として渡されます。 GET メソッドについては[[GuideNewAction|後述]]しますが、URL にパラメーターを付ける方法だと思っておいてください。 |
||
104 | サンプルのアドレスは以下のようになります。(プロジェクトの識別名は demo にしています) |
||
105 | 1 | Mitsuyoshi Yoshida | |
106 | <pre> |
||
107 | 6 | Mitsuyoshi Yoshida | http://127.0.0.1:3000/foos/index?project_id=demo |
108 | 1 | Mitsuyoshi Yoshida | </pre> |
109 | |||
110 | このアドレスの指定によりコントロールのアクションが実行されることになります。この場合は FoosController の index メソッドが呼ばれます。 |
||
111 | ID は *params* というハッシュクラスの変数に格納されてます。params は $ マークは付いてませんが、グローバル変数のようなものだと考えてください。 |
||
112 | |||
113 | |||
114 | 6 | Mitsuyoshi Yoshida | h3. Redmine の場合 |
115 | 1 | Mitsuyoshi Yoshida | |
116 | 6 | Mitsuyoshi Yoshida | Rails のアプリケーションではこの :id にプロジェクトの識別名を入れてつかうことが多いです。 |
117 | しかし、 Redmine ではチケットなどで、プロジェクトの識別名を :id を使わずに :project_id に入れて、チケットなどの ID を :id に入れています。サンプルでもそれにあわせるようにしています。 |
||
118 | 1 | Mitsuyoshi Yoshida | |
119 | 6 | Mitsuyoshi Yoshida | しかし、チケットを表示した場合などの URL をみてもらうと Redmine では @?project_id=demo@ のような表記はありません。 これは Rails の routes の機能を使って URL を変えているためです。 |
120 | |||
121 | 8 | NAITOH Jun | なお Redmine 1.4 以降ではデフォルトの routes 設定が提供されなくなりました。このため各プラグインは適切な routes を個別に設定する必要があります。 |
122 | 6 | Mitsuyoshi Yoshida | |
123 | h3. routes |
||
124 | |||
125 | 8 | NAITOH Jun | URL を設定するため config/routes.rb にどのように設定するかといった指定を記述します。 |
126 | 6 | Mitsuyoshi Yoshida | ここでは、 Redmine にあわせてメニューのアドレスが次のようになるようにします。 |
127 | |||
128 | <pre> |
||
129 | http://127.0.0.1:3000/projects/demo/foos/index |
||
130 | </pre> |
||
131 | |||
132 | config/routes.rb に以下の内容のファイルを作成して下さい。 |
||
133 | |||
134 | <pre><code class="ruby"> |
||
135 | 8 | NAITOH Jun | # Plugin's routes |
136 | # See: http://guides.rubyonrails.org/routing.html |
||
137 | Rails.application.routes.draw do |
||
138 | match 'projects/:project_id/foos/:action', :to => 'foos' |
||
139 | match 'projects/:project_id/foos/:action/:id', :to => 'foos' |
||
140 | 6 | Mitsuyoshi Yoshida | end |
141 | </code></pre> |
||
142 | |||
143 | |||
144 | |||
145 | 1 | Mitsuyoshi Yoshida | h2. index ページの表示 |
146 | |||
147 | Redmine を再起動してモジュールを追加したプロジェクトを開いてみましょう。プロジェクトメニューに *Standard* が追加されています。 |
||
148 | |||
149 | !sample_proj_menu.png! |
||
150 | |||
151 | このメニューをクリックして下さい。 index.html.erb の内容のページが表示されます。 |
||
152 | |||
153 | !index_no_project.png! |
||
154 | |||
155 | コントローラの index メソッドの中にはまだ何も書いていません。それにもかかわらず、 index ページが表示されています。これはコントローラのアクションが実行されるとアクション名のメソッドが実行され、デフォルトの状態ではアクション名に対応する views のファイルが表示されるためです。 |
||
156 | |||
157 | |||
158 | h2. @project の設定 |
||
159 | |||
160 | ただし、表示されたページよく見ると何か変なことに気づくと思います。これは他のプロジェクトメニューと違いプロジェクトが開かれていないためです。このページをプロジェクトに属するものするためには FoosController クラスのインスタンス変数 *@project* に値を設定する必要があります。 |
||
161 | |||
162 | 8 | NAITOH Jun | |
163 | |||
164 | app/controllers/foos_controller.rb の FoosController クラスの末尾に次のような @project を設定する *find_project* メソッドの定義を追加します。外から呼ばれることはありませんので、private メソッドにしています。 |
||
165 | 6 | Mitsuyoshi Yoshida | <pre><code class="ruby"> |
166 | class FoosController < ApplicationController |
||
167 | 7 | Mitsuyoshi Yoshida | unloadable |
168 | # : |
||
169 | private |
||
170 | def find_project |
||
171 | @project = Project.find(params[:project_id]) |
||
172 | rescue ActiveRecord::RecordNotFound |
||
173 | render_404 |
||
174 | end |
||
175 | 6 | Mitsuyoshi Yoshida | end |
176 | </code></pre> |
||
177 | 1 | Mitsuyoshi Yoshida | |
178 | 6 | Mitsuyoshi Yoshida | params[:id] にはプロジェクトの識別名が入っています。 |
179 | Project はプロジェクト用のモデルクラスです。 *find* メソッドは引数にプロジェクト識別名を渡すと、データベースから識別名が一致するプロジェクトを探し、Project のオブジェクトを返すクラスメソッドです。 |
||
180 | |||
181 | Project クラスも ActiveRecord::Base クラスを継承して作成されており、データがみつからないと *ActiveRecord::RecordNotFound* の例外が発生します。コントローラ内で例外が発生すると通常の http サーバの場合 Internal Error のページになってしまいます。(WEBrick では詳細なエラー情報の画面になります。) |
||
182 | この例外をキャッチして *render_404* を実行しています。 これはファイルが見つかりませんといった http の 404 エラーのページを表示するメソッドです。 |
||
183 | |||
184 | 定義した find_project メソッドを index メソッドの中で呼び出せばプロジェクト内のページとして表示されます。 |
||
185 | 1 | Mitsuyoshi Yoshida | |
186 | |||
187 | h2. before_filter |
||
188 | |||
189 | アクションは index だけではありません。他のアクションのメソッドでも同様に find_project を呼び出す必要があります。じゃ、 index の find_project をコピーして、他のメソッドにもペーストしていって ... と思った人はちょっと待ってください。 それでは同じことを何度も書く羽目になります。 Rails には DRY(Don't Repeat Yourself) という繰り返し禁止の方針がありました。何か繰り返しを避ける方法があるはずです。 |
||
190 | |||
191 | 実際、避ける方法は用意されています。それは *before_filter* です。これでメソッドを指定するとそのメソッドはアクションのメソッドの前に呼ばれるようになります。 |
||
192 | こちらはコントローラクラスの先頭の方に追加します。 |
||
193 | |||
194 | <pre><code class="ruby"> |
||
195 | class FoosController < ApplicationController |
||
196 | unloadable |
||
197 | before_filter :find_project |
||
198 | # : |
||
199 | </code></pre> |
||
200 | |||
201 | |||
202 | h2. authorize |
||
203 | |||
204 | before_filter はカンマで区切って複数のメソッドを指定することが出来ます。もう一つ追加してみましょう。 |
||
205 | <pre><code class="ruby"> |
||
206 | class FoosController < ApplicationController |
||
207 | unloadable |
||
208 | before_filter :find_project, :authorize |
||
209 | # : |
||
210 | </code></pre> |
||
211 | |||
212 | 追加した *authorize* はページを開いた時にログインしていない場合はログインのページ行く Redmine のメソッドです。通常、プロジェクトメニューから開かれるので、ログインしていることが多いと思いますが、ブラウザで前に開いていたページをもう一度開くといった設定がしてある場合などでは直接ページが指定されることもあります。そういったときにもちゃんとログインできるようにすべてのアクションの前に実行しておく必要があります。 |
||
213 | |||
214 | 権限の設定で index や show では設定によってはログインしてなくても、表示できる場合があるのではと疑問を持った方もいると思いますが、そういう場合も Redmine がログインしないように上手く処理してくれます。 |
||
215 | |||
216 | 権限の判定には現在のプロジェクトの情報が必要となります。before_filter は追加した順に実行されますので必ず find_project, authorize の順で記述して下さい。 |
||
217 | |||
218 | ここまで設定して、もう一度 [Standard] のメニューを選択してみてください。今度はプロジェクトのページとして開かれているはずです。 |
||
219 | |||
220 | !index_no_tab.png! |
||
221 | |||
222 | まだ、少し変なところがあります。メニュー項目が選択状態になっていませんね。これを解決するにはコントローラ内で *menu_item* を使ってメニュー項目を指定します。 |
||
223 | |||
224 | <pre><code class="ruby"> |
||
225 | menu_item :メニュー項目のシンボル |
||
226 | </code></pre> |
||
227 | |||
228 | このメソッドで指定しなくてもメニュー項目が選択状態になることがあります。実はどうしたらそうなるのかは私もよく分かりません。とりあえず、選択状態にならないときはこのメソッドで指定してみてください。 |
||
229 | |||
230 | これまでの記述を追加したコントローラのファイルの中身は次のようになります。 |
||
231 | |||
232 | <pre><code class="ruby"> |
||
233 | class FoosController < ApplicationController |
||
234 | unloadable |
||
235 | menu_item :standard |
||
236 | before_filter :find_project, :authorize |
||
237 | |||
238 | |||
239 | def index |
||
240 | end |
||
241 | |||
242 | |||
243 | def new |
||
244 | end |
||
245 | |||
246 | |||
247 | def show |
||
248 | end |
||
249 | |||
250 | |||
251 | def edit |
||
252 | end |
||
253 | |||
254 | private |
||
255 | def find_project |
||
256 | @project = Project.find(params[:id]) |
||
257 | rescue ActiveRecord::RecordNotFound |
||
258 | render_404 |
||
259 | end |
||
260 | end |
||
261 | </code></pre> |
||
262 | |||
263 | これでプロジェクトメニューにきちんと登録できるようになりました。 |
||
264 | |||
265 | !index_tab.png! |
||
266 | |||
267 | ---- |
||
268 | |||
269 | | [[プラグイン開発ガイド|^]] | [[GuideControlSkelton|<<]] | [[GuideI18n|>>]] | |