README.textile in be9-acl9-0.9.1 vs README.textile in be9-acl9-0.9.2
- old
+ new
@@ -43,11 +43,11 @@
Acl9 can be installed as a gem from "GitHub":http://github.com.
Add the following line to your @config/environment.rb@:
<pre><code>
- config.gem "be9-acl9", :source => "http://gems.github.com"
+ config.gem "be9-acl9", :source => "http://gems.github.com", :lib => "acl9"
</pre></code>
Then run @rake gems:install@ (with possible @rake gems:unpack@ thereafter) and you're done!
Alternatively you can install Acl9 as a plugin:
@@ -116,11 +116,11 @@
Role control subsystem has been lifted from
"Rails authorization plugin":http://github.com/DocSavage/rails-authorization-plugin,
but undergone some modifications.
It's based on two tables in the database. First, role table, which stores pairs @[role_name, object]@
-where object is a polymorphic link or a class. Second, join table, which joins users and roles.
+where object is a polymorphic model instance or a class. Second, join table, which joins users and roles.
To use this subsystem, you should define a @Role@ model.
h2. Role model
@@ -140,11 +140,11 @@
t.datetime "created_at"
t.datetime "updated_at"
end
</code></pre>
-Note that you will never use the @Role@ class directly.
+Note that you will almost never use the @Role@ class directly.
h2. Subject model
<pre><code>
class User < ActiveRecord::Base
@@ -331,21 +331,21 @@
user.has_role? :manager, foo # => false
user.has_role? :manager # => true
</code></pre>
-Our @user@ is no more manager of @foo@, but is now a manager of @bar@.
+Our @user@ is no more manager of @foo@, but has become a manager of @bar@.
<pre><code>
user.has_no_roles!
user.has_role? :manager # => false
user.has_role? :admin # => false
user.roles # => []
</code></pre>
-Now @user@ has no roles in the system.
+At this time @user@ has no roles in the system.
h2. Coming up with your own role implementation
The described role system with its 2 tables (not counting the @users@ table!)
might be an overkill for many cases. If all you want is global roles without
@@ -379,11 +379,11 @@
By means of access control subsystem you can protect actions of your controller
from unauthorized access. Acl9 provides a nice DSL for writing access rules.
h2. Allow and deny
-Access control is mostly about allowing and denying. So there two
+Access control is mostly about allowing and denying. So there are two
basic methods: @allow@ and @deny@. They have the same syntax:
<pre><code>
allow ROLE_LIST, OPTIONS
deny ROLE_LIST, OPTIONS
@@ -395,27 +395,27 @@
<pre><code>
allow :manager, :admin
deny :banned
</code></pre>
-will match holders of global role _manager_ *and* holders of global role _admin_ as allowed and
-_banned_ as denied.
+will match holders of global role _manager_ *and* holders of global role _admin_ as allowed.
+On the contrary, holders of _banned_ role will match as denied.
Basically this snippet is equivalent to
<pre><code>
allow :manager
allow :admin
deny :banned
</code></pre>
-which means that roles in argument list is OR'ed for a match, and not AND'ed.
+which means that roles in argument list are OR'ed for a match, and not AND'ed.
Also note that:
* You may use both strings and :symbols to specify roles (the latter get converted into strings).
* Role names are singularized before check.
-The mentioned snippet can thus be written as
+Thus the snippet above can also be written as
<pre><code>
allow :managers, :admins
deny 'banned'
</code></pre>
@@ -438,11 +438,11 @@
allow :interested, :in => Future
deny :short, :on => :time
deny :hated, :by => :us
</code></pre>
-So, to specify an object you use one of the 6 preposition options:
+To specify an object you use one of the 6 preposition options:
* :of
* :at
* :on
* :by
* :for
@@ -480,12 +480,10 @@
@moorble = Moorble.find(params[:id])
end
end
</code></pre>
-
-
Note that the object option is applied to all of the roles you specify in the argument list.
As such,
<pre><code>
allow :devil, :son, :of => God
@@ -587,11 +585,11 @@
| None of the @allow@ and @deny@ rules matched. | Access is allowed. | Access is denied. |
| Some of the @allow@ rules matched, none of the @deny@ rules matched. | Access is allowed. | Access is allowed. |
| None of the @allow@ rules matched, some of the @deny@ rules matched. | Access is denied. | Access is denied. |
| Some of the @allow@ rules matched, some of the @deny@ rules matched. | Access is allowed. | Access is denied. |
-Apparently _default deny_ mode is stricter, that's because it's on by default.
+Apparently _default deny_ mode is more strict, and that's because it's on by default.
h2. Actions block
You may group rules with the help of the @actions@ block.
@@ -642,15 +640,16 @@
# a method, returning @true@ or @false@, whether access is allowed or denied.
First case is by default. You can catch the exception with @rescue_from@ call and do something
you like: make a redirect, or render "Access denied" template, or whatever.
-Second case is obtained with @:as_method@ option (see below) and may be helpful if you want
-to use @skip_before_filter@ somewhere on the derived controller.
+Second case is obtained with specifying method name as an argument to
+@access_control@ (or using @:as_method@ option, see below) and may be helpful
+if you want to use @skip_before_filter@ somewhere in the derived controller.
-Third case will take place if you use @:as_method@ with @:filter => false@. You'll get an ordinary
-method which you can call anywhere you want.
+Third case will take place if you supply @:filter => false@ along with method
+name. You'll get an ordinary method which you can call anywhere you want.
h3. :subject_method
Acl9 obtains the subject instance by calling specific method of the controller. By default it's
@:current_user@, but you may change it.
@@ -692,18 +691,34 @@
end
</code></pre>
access control checks will be added as @acl@ method onto MyController, with @before_filter :acl@ call thereafter.
+Instead of using @:as_method@ you may specify the name of the method as a positional argument
+to @access_control@:
+
+<pre><code>
+ class MyController < ApplicationController
+ access_control :acl do
+ # ...
+ end
+
+ # ...
+ end
+</code></pre>
+
+
h3. :filter
-If you set @:filter@ to @false@ (it's @true@ by default) and also use @:as_method@, you'll get a method
-which won't raise @Acl9::AccessDenied@ exception, but rather return @true@ or @false@ (access allowed/denied).
+If you set @:filter@ to @false@ (it's @true@ by default) and also use
+@:as_method@ (or method name as 1st argument to @access_control@, you'll get a
+method which won't raise @Acl9::AccessDenied@ exception, but rather return
+@true@ or @false@ (access allowed/denied).
<pre><code>
class SecretController < ApplicationController
- access_control :as_method => :secret_access?, :filter => false do
+ access_control :secret_access?, :filter => false do
allow :james_bond
# ...
end
def index
@@ -726,10 +741,30 @@
# ...
end
end
</code></pre>
+The generated method can receive an objects hash as an argument. In this example,
+
+<pre><code>
+ class LolController < ApplicationController
+ access_control :lolcats?, :filter => false do
+ allow :cats, :by => :lol
+ # ...
+ end
+ end
+</code></pre>
+
+you may not only call @lolcats?@ with no arguments, which will basically return
+
+<pre><code>
+ current_user.has_role?('cats', @lol)
+</code></pre>
+
+but also as @lolcats?(:lol => Lol.find(params[:lol]))@. The hash will be looked into first,
+even if you have an instance variable @lol@.
+
h3. Other options
Other options will be passed to @before_filter@. As such, you may use @:only@ and @:except@ to narrow
the action scope of the whole ACL block.
@@ -760,6 +795,8 @@
# ...
end
</code></pre>
-Copyright (c) 2009 Oleg Dashevskii, released under the MIT license
+Copyright (c) 2009 Oleg Dashevskii, released under the MIT license.
+
+Contact me at "#{%w(Oleg Dashevskii).join('').downcase}@gmail.com"