Adding some documentation.
[lyrix.git] / doc / app / classes / AuthenticatedSystem.html
blob49b2377d0f4388dd3e7541450aca81ad3324828b
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE html
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8 <title>Module: AuthenticatedSystem</title>
9 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
10 <meta http-equiv="Content-Script-Type" content="text/javascript" />
11 <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
12 <script type="text/javascript">
13 // <![CDATA[
15 function popupCode( url ) {
16 window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
19 function toggleCode( id ) {
20 if ( document.getElementById )
21 elem = document.getElementById( id );
22 else if ( document.all )
23 elem = eval( "document.all." + id );
24 else
25 return false;
27 elemStyle = elem.style;
29 if ( elemStyle.display != "block" ) {
30 elemStyle.display = "block"
31 } else {
32 elemStyle.display = "none"
35 return true;
38 // Make codeblocks hidden by default
39 document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
41 // ]]>
42 </script>
44 </head>
45 <body>
49 <div id="classHeader">
50 <table class="header-table">
51 <tr class="top-aligned-row">
52 <td><strong>Module</strong></td>
53 <td class="class-name-in-header">AuthenticatedSystem</td>
54 </tr>
55 <tr class="top-aligned-row">
56 <td><strong>In:</strong></td>
57 <td>
58 <a href="../files/lib/authenticated_system_rb.html">
59 lib/authenticated_system.rb
60 </a>
61 <br />
62 </td>
63 </tr>
65 </table>
66 </div>
67 <!-- banner header -->
69 <div id="bodyContent">
73 <div id="contextContent">
77 </div>
79 <div id="method-list">
80 <h3 class="section-bar">Methods</h3>
82 <div class="name-list">
83 <a href="#M000048">access_denied</a>&nbsp;&nbsp;
84 <a href="#M000046">authorized?</a>&nbsp;&nbsp;
85 <a href="#M000044">current_user</a>&nbsp;&nbsp;
86 <a href="#M000045">current_user=</a>&nbsp;&nbsp;
87 <a href="#M000051">included</a>&nbsp;&nbsp;
88 <a href="#M000043">logged_in?</a>&nbsp;&nbsp;
89 <a href="#M000052">login_from_cookie</a>&nbsp;&nbsp;
90 <a href="#M000047">login_required</a>&nbsp;&nbsp;
91 <a href="#M000042">offline?</a>&nbsp;&nbsp;
92 <a href="#M000050">redirect_back_or_default</a>&nbsp;&nbsp;
93 <a href="#M000049">store_location</a>&nbsp;&nbsp;
94 </div>
95 </div>
97 </div>
100 <!-- if includes -->
102 <div id="section">
111 <!-- if method_list -->
112 <div id="methods">
113 <h3 class="section-bar">Protected Class methods</h3>
115 <div id="method-M000051" class="method-detail">
116 <a name="M000051"></a>
118 <div class="method-heading">
119 <a href="#M000051" class="method-signature">
120 <span class="method-name">included</span><span class="method-args">(base)</span>
121 </a>
122 </div>
124 <div class="method-description">
126 Inclusion hook to make <a
127 href="AuthenticatedSystem.html#M000044">current_user</a> and <a
128 href="AuthenticatedSystem.html#M000043">logged_in?</a> available as
129 ActionView helper methods.
130 </p>
131 <p><a class="source-toggle" href="#"
132 onclick="toggleCode('M000051-source');return false;">[Source]</a></p>
133 <div class="method-source-code" id="M000051-source">
134 <pre>
135 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 106</span>
136 106: <span class="ruby-keyword kw">def</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">included</span>(<span class="ruby-identifier">base</span>)
137 107: <span class="ruby-identifier">base</span>.<span class="ruby-identifier">send</span> <span class="ruby-identifier">:helper_method</span>, <span class="ruby-identifier">:current_user</span>, <span class="ruby-identifier">:logged_in?</span>, <span class="ruby-identifier">:offline?</span>
138 108: <span class="ruby-keyword kw">end</span>
139 </pre>
140 </div>
141 </div>
142 </div>
144 <h3 class="section-bar">Protected Instance methods</h3>
146 <div id="method-M000048" class="method-detail">
147 <a name="M000048"></a>
149 <div class="method-heading">
150 <a href="#M000048" class="method-signature">
151 <span class="method-name">access_denied</span><span class="method-args">()</span>
152 </a>
153 </div>
155 <div class="method-description">
157 Redirect as appropriate when an access request fails.
158 </p>
160 The default action is to redirect to the login screen.
161 </p>
163 Override this method in your controllers if you want to have special
164 behavior in case the user is not authorized to access the requested action.
165 For example, a popup window might simply close itself.
166 </p>
167 <p><a class="source-toggle" href="#"
168 onclick="toggleCode('M000048-source');return false;">[Source]</a></p>
169 <div class="method-source-code" id="M000048-source">
170 <pre>
171 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 75</span>
172 75: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">access_denied</span>
173 76: <span class="ruby-identifier">respond_to</span> <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">accepts</span><span class="ruby-operator">|</span>
174 77: <span class="ruby-identifier">accepts</span>.<span class="ruby-identifier">html</span> <span class="ruby-keyword kw">do</span>
175 78: <span class="ruby-identifier">store_location</span>
176 79: <span class="ruby-identifier">redirect_to</span> <span class="ruby-identifier">:controller</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value str">'sessions'</span>, <span class="ruby-identifier">:action</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value str">'new'</span>
177 80: <span class="ruby-keyword kw">end</span>
178 81: <span class="ruby-identifier">accepts</span>.<span class="ruby-identifier">xml</span> <span class="ruby-keyword kw">do</span>
179 82: <span class="ruby-identifier">headers</span>[<span class="ruby-value str">&quot;Status&quot;</span>] = <span class="ruby-value str">&quot;Unauthorized&quot;</span>
180 83: <span class="ruby-identifier">headers</span>[<span class="ruby-value str">&quot;WWW-Authenticate&quot;</span>] = <span class="ruby-value str">%(Basic realm=&quot;Web Password&quot;)</span>
181 84: <span class="ruby-identifier">render</span> <span class="ruby-identifier">:text</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value str">&quot;Couldn't authenticate you&quot;</span>, <span class="ruby-identifier">:status</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value str">'401 Unauthorized'</span>
182 85: <span class="ruby-keyword kw">end</span>
183 86: <span class="ruby-keyword kw">end</span>
184 87: <span class="ruby-keyword kw">false</span>
185 88: <span class="ruby-keyword kw">end</span>
186 </pre>
187 </div>
188 </div>
189 </div>
191 <div id="method-M000046" class="method-detail">
192 <a name="M000046"></a>
194 <div class="method-heading">
195 <a href="#M000046" class="method-signature">
196 <span class="method-name">authorized?</span><span class="method-args">()</span>
197 </a>
198 </div>
200 <div class="method-description">
202 Check if the user is authorized.
203 </p>
205 Override this method in your controllers if you want to restrict access to
206 only a few actions or if you want to check if the user has the correct
207 rights.
208 </p>
210 Example:
211 </p>
212 <pre>
213 # only allow nonbobs
214 def authorize?
215 current_user.login != &quot;bob&quot;
217 </pre>
218 <p><a class="source-toggle" href="#"
219 onclick="toggleCode('M000046-source');return false;">[Source]</a></p>
220 <div class="method-source-code" id="M000046-source">
221 <pre>
222 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 43</span>
223 43: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">authorized?</span>
224 44: <span class="ruby-keyword kw">true</span>
225 45: <span class="ruby-keyword kw">end</span>
226 </pre>
227 </div>
228 </div>
229 </div>
231 <div id="method-M000044" class="method-detail">
232 <a name="M000044"></a>
234 <div class="method-heading">
235 <a href="#M000044" class="method-signature">
236 <span class="method-name">current_user</span><span class="method-args">()</span>
237 </a>
238 </div>
240 <div class="method-description">
242 Accesses the current user from the session.
243 </p>
244 <p><a class="source-toggle" href="#"
245 onclick="toggleCode('M000044-source');return false;">[Source]</a></p>
246 <div class="method-source-code" id="M000044-source">
247 <pre>
248 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 13</span>
249 13: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">current_user</span>
250 14: <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">offline?</span>
251 15: <span class="ruby-ivar">@current_user</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">User</span>.<span class="ruby-identifier">find</span>(<span class="ruby-identifier">:first</span>) <span class="ruby-operator">||</span> <span class="ruby-identifier">:false</span>
252 16: <span class="ruby-keyword kw">else</span>
253 17: <span class="ruby-ivar">@current_user</span> <span class="ruby-operator">||=</span> (<span class="ruby-identifier">session</span>[<span class="ruby-identifier">:user</span>] <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-constant">User</span>.<span class="ruby-identifier">find_by_id</span>(<span class="ruby-identifier">session</span>[<span class="ruby-identifier">:user</span>])) <span class="ruby-operator">||</span> <span class="ruby-identifier">:false</span>
254 18: <span class="ruby-keyword kw">end</span>
255 19: <span class="ruby-keyword kw">end</span>
256 </pre>
257 </div>
258 </div>
259 </div>
261 <div id="method-M000045" class="method-detail">
262 <a name="M000045"></a>
264 <div class="method-heading">
265 <a href="#M000045" class="method-signature">
266 <span class="method-name">current_user=</span><span class="method-args">(new_user)</span>
267 </a>
268 </div>
270 <div class="method-description">
272 Store the given user in the session.
273 </p>
274 <p><a class="source-toggle" href="#"
275 onclick="toggleCode('M000045-source');return false;">[Source]</a></p>
276 <div class="method-source-code" id="M000045-source">
277 <pre>
278 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 22</span>
279 22: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">current_user=</span>(<span class="ruby-identifier">new_user</span>)
280 23: <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">offline?</span>
281 24: <span class="ruby-ivar">@current_user</span> = <span class="ruby-identifier">new_user</span>
282 25: <span class="ruby-keyword kw">else</span>
283 26: <span class="ruby-identifier">session</span>[<span class="ruby-identifier">:user</span>] = (<span class="ruby-identifier">new_user</span>.<span class="ruby-identifier">nil?</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">new_user</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">Symbol</span>)) <span class="ruby-operator">?</span> <span class="ruby-keyword kw">nil</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">new_user</span>.<span class="ruby-identifier">id</span>
284 27: <span class="ruby-ivar">@current_user</span> = <span class="ruby-identifier">new_user</span>
285 28: <span class="ruby-keyword kw">end</span>
286 29: <span class="ruby-keyword kw">end</span>
287 </pre>
288 </div>
289 </div>
290 </div>
292 <div id="method-M000043" class="method-detail">
293 <a name="M000043"></a>
295 <div class="method-heading">
296 <a href="#M000043" class="method-signature">
297 <span class="method-name">logged_in?</span><span class="method-args">()</span>
298 </a>
299 </div>
301 <div class="method-description">
303 Returns true or false if the user is logged in. Preloads @<a
304 href="AuthenticatedSystem.html#M000044">current_user</a> with the user
305 model if they&#8217;re logged in.
306 </p>
307 <p><a class="source-toggle" href="#"
308 onclick="toggleCode('M000043-source');return false;">[Source]</a></p>
309 <div class="method-source-code" id="M000043-source">
310 <pre>
311 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 8</span>
312 8: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">logged_in?</span>
313 9: <span class="ruby-identifier">current_user</span> <span class="ruby-operator">!=</span> <span class="ruby-identifier">:false</span>
314 10: <span class="ruby-keyword kw">end</span>
315 </pre>
316 </div>
317 </div>
318 </div>
320 <div id="method-M000052" class="method-detail">
321 <a name="M000052"></a>
323 <div class="method-heading">
324 <a href="#M000052" class="method-signature">
325 <span class="method-name">login_from_cookie</span><span class="method-args">()</span>
326 </a>
327 </div>
329 <div class="method-description">
331 When called with before_filter :<a
332 href="AuthenticatedSystem.html#M000052">login_from_cookie</a> will check
333 for an :auth_token cookie and log the user back in if apropriate
334 </p>
335 <p><a class="source-toggle" href="#"
336 onclick="toggleCode('M000052-source');return false;">[Source]</a></p>
337 <div class="method-source-code" id="M000052-source">
338 <pre>
339 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 112</span>
340 112: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">login_from_cookie</span>
341 113: <span class="ruby-keyword kw">return</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">cookies</span>[<span class="ruby-identifier">:auth_token</span>] <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-operator">!</span><span class="ruby-identifier">logged_in?</span>
342 114: <span class="ruby-identifier">user</span> = <span class="ruby-constant">User</span>.<span class="ruby-identifier">find_by_remember_token</span>(<span class="ruby-identifier">cookies</span>[<span class="ruby-identifier">:auth_token</span>])
343 115: <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">user</span> <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">user</span>.<span class="ruby-identifier">remember_token?</span>
344 116: <span class="ruby-identifier">user</span>.<span class="ruby-identifier">remember_me</span>
345 117: <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">current_user</span> = <span class="ruby-identifier">user</span>
346 118: <span class="ruby-identifier">cookies</span>[<span class="ruby-identifier">:auth_token</span>] = { <span class="ruby-identifier">:value</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">current_user</span>.<span class="ruby-identifier">remember_token</span> , <span class="ruby-identifier">:expires</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">current_user</span>.<span class="ruby-identifier">remember_token_expires_at</span> }
347 119: <span class="ruby-identifier">flash</span>[<span class="ruby-identifier">:notice</span>] = <span class="ruby-value str">&quot;Logged in successfully&quot;</span>
348 120: <span class="ruby-keyword kw">end</span>
349 121: <span class="ruby-keyword kw">end</span>
350 </pre>
351 </div>
352 </div>
353 </div>
355 <div id="method-M000047" class="method-detail">
356 <a name="M000047"></a>
358 <div class="method-heading">
359 <a href="#M000047" class="method-signature">
360 <span class="method-name">login_required</span><span class="method-args">()</span>
361 </a>
362 </div>
364 <div class="method-description">
366 Filter method to enforce a login requirement.
367 </p>
369 To require logins for all actions, use this in your controllers:
370 </p>
371 <pre>
372 before_filter :login_required
373 </pre>
375 To require logins for specific actions, use this in your controllers:
376 </p>
377 <pre>
378 before_filter :login_required, :only =&gt; [ :edit, :update ]
379 </pre>
381 To skip this in a subclassed controller:
382 </p>
383 <pre>
384 skip_before_filter :login_required
385 </pre>
386 <p><a class="source-toggle" href="#"
387 onclick="toggleCode('M000047-source');return false;">[Source]</a></p>
388 <div class="method-source-code" id="M000047-source">
389 <pre>
390 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 61</span>
391 61: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">login_required</span>
392 62: <span class="ruby-identifier">username</span>, <span class="ruby-identifier">passwd</span> = <span class="ruby-identifier">get_auth_data</span>
393 63: <span class="ruby-keyword kw">self</span>.<span class="ruby-identifier">current_user</span> <span class="ruby-operator">||=</span> <span class="ruby-constant">User</span>.<span class="ruby-identifier">authenticate</span>(<span class="ruby-identifier">username</span>, <span class="ruby-identifier">passwd</span>) <span class="ruby-operator">||</span> <span class="ruby-identifier">:false</span> <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">username</span> <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">passwd</span>
394 64: <span class="ruby-identifier">logged_in?</span> <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">authorized?</span> <span class="ruby-value">? </span><span class="ruby-keyword kw">true</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">access_denied</span>
395 65: <span class="ruby-keyword kw">end</span>
396 </pre>
397 </div>
398 </div>
399 </div>
401 <div id="method-M000042" class="method-detail">
402 <a name="M000042"></a>
404 <div class="method-heading">
405 <a href="#M000042" class="method-signature">
406 <span class="method-name">offline?</span><span class="method-args">()</span>
407 </a>
408 </div>
410 <div class="method-description">
411 <p><a class="source-toggle" href="#"
412 onclick="toggleCode('M000042-source');return false;">[Source]</a></p>
413 <div class="method-source-code" id="M000042-source">
414 <pre>
415 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 3</span>
416 3: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">offline?</span>
417 4: (<span class="ruby-constant">ENV</span>[<span class="ruby-value str">'OFFLINE_MODE'</span>]) <span class="ruby-operator">?</span> (<span class="ruby-constant">ENV</span>[<span class="ruby-value str">'OFFLINE_MODE'</span>] <span class="ruby-operator">==</span> <span class="ruby-value str">'true'</span>) <span class="ruby-operator">:</span> <span class="ruby-keyword kw">false</span>
418 5: <span class="ruby-keyword kw">end</span>
419 </pre>
420 </div>
421 </div>
422 </div>
424 <div id="method-M000050" class="method-detail">
425 <a name="M000050"></a>
427 <div class="method-heading">
428 <a href="#M000050" class="method-signature">
429 <span class="method-name">redirect_back_or_default</span><span class="method-args">(default)</span>
430 </a>
431 </div>
433 <div class="method-description">
435 Redirect to the URI stored by the most recent <a
436 href="AuthenticatedSystem.html#M000049">store_location</a> call or to the
437 passed default.
438 </p>
439 <p><a class="source-toggle" href="#"
440 onclick="toggleCode('M000050-source');return false;">[Source]</a></p>
441 <div class="method-source-code" id="M000050-source">
442 <pre>
443 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 99</span>
444 99: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">redirect_back_or_default</span>(<span class="ruby-identifier">default</span>)
445 100: <span class="ruby-identifier">session</span>[<span class="ruby-identifier">:return_to</span>] <span class="ruby-operator">?</span> <span class="ruby-identifier">redirect_to</span>(<span class="ruby-identifier">session</span>[<span class="ruby-identifier">:return_to</span>]) <span class="ruby-operator">:</span> <span class="ruby-identifier">redirect_to</span>(<span class="ruby-identifier">default</span>)
446 101: <span class="ruby-identifier">session</span>[<span class="ruby-identifier">:return_to</span>] = <span class="ruby-keyword kw">nil</span>
447 102: <span class="ruby-keyword kw">end</span>
448 </pre>
449 </div>
450 </div>
451 </div>
453 <div id="method-M000049" class="method-detail">
454 <a name="M000049"></a>
456 <div class="method-heading">
457 <a href="#M000049" class="method-signature">
458 <span class="method-name">store_location</span><span class="method-args">()</span>
459 </a>
460 </div>
462 <div class="method-description">
464 Store the URI of the current request in the session.
465 </p>
467 We can return to this location by calling <a
468 href="AuthenticatedSystem.html#M000050">redirect_back_or_default</a>.
469 </p>
470 <p><a class="source-toggle" href="#"
471 onclick="toggleCode('M000049-source');return false;">[Source]</a></p>
472 <div class="method-source-code" id="M000049-source">
473 <pre>
474 <span class="ruby-comment cmt"># File lib/authenticated_system.rb, line 93</span>
475 93: <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">store_location</span>
476 94: <span class="ruby-identifier">session</span>[<span class="ruby-identifier">:return_to</span>] = <span class="ruby-identifier">request</span>.<span class="ruby-identifier">request_uri</span>
477 95: <span class="ruby-keyword kw">end</span>
478 </pre>
479 </div>
480 </div>
481 </div>
484 </div>
487 </div>
490 <div id="validator-badges">
491 <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
492 </div>
494 </body>
495 </html>