ruby script/plugin install svn://rubyforge.org/var/svn/activeacl/trunk

In short
===========
"No access defined" for a privilege evaluates to "deny". This may be overriden by an explicit "allow" or "deny". Privileges are inherited in requestor and target groups, this means you can override them in subgroups again. Privileges directly assigned to an object always supercede those assigned to groups.

Simple (2D) permissions
---------------------------
We want all registered users to be able to log in. We create the User model, the UserGroup model and the User::LOGIN privilege object as described above. Then we create a new ACL entry, set 'allow' to true, add the "registered users" group as requester group, User::LOGIN as privilege and we are done. Every user assigned to "registered users" or a subgroup of it will now be granted access by calling my_user.has_privilege?(User::LOGIN).

Simple permissions example

  class UserGroup < ActiveRecord::Base
    acts_as_nested_set
    acts_as_access_group
    has_and_belongs_to_many :users
  end

  class User < ActiveRecord::Base
    has_and_belongs_to_many :user_groups
    acts_as_access_object :grouped_by => :user_groups
    privilege_const_set('LOGIN')
  end

  # assume 'registered_users' exists and users 'john' and 'dr_evil' are members of it but 'anonymous' is not. 
  registered_users = UserGroup.find_by_name('registered_users')

  acl = ActiveAcl::Acl.create :section => ActiveAcl::AclSection.create(:description => 'users')

  acl.allow = true # true is default
  acl.privileges << User::LOGIN
  acl.requester_groups << registered_users

  acl.save

  john.has_privilege?(User::LOGIN) #=> true
  dr_evil.has_privilege?(User::LOGIN) #=> true

  anonymous.has_privilege?(User::LOGIN) #=> false

Overriding permissions
-----------------------
We want to ban specific users from our site. We create another ACL entry, assign the User::LOGIN privilege object, set 'allow' to false and then assign these users as requesters to the ACL entry. The direct permission assignment on the objects overrides the 'allow login' ACL entry from above.

Overriding permissions example

  ban_users = ActiveAcl::Acl.create :section => ActiveAcl::AclSection.find_by_description('users')

  ban_users.allow = false
  ban_users.privileges << User::LOGIN
  ban_users.requesters << dr_evil

  ban_users.save

  john.has_privilege?(User::LOGIN) #=> true
  dr_evil.has_privilege?(User::LOGIN) #=> false

Object level (3D) permissions
------------------------------
We want to assign forum permissions. We have several privileges (Forum::ADMIN, Forum::READ, Forum::POST etc.), the afore mentioned User and UserGroup models as well as a Forum and a Category model for grouping the forums.

If we want to check if a certain user may read in a certain forum, it is not sufficient to check test_user.has_privilege?(Forum::READ) as the target object - in this case a forum - is needed to make a decision. The code to do the check is like test_user.has_privilege?(Forum::READ, :on => teamforum).

To make this work you create a new ACL entry, add Forum::POST and Forum::READ as privileges, set 'allow' to true, add the registered users group as a requester group and the public forums category as a target group to the acl. Now every user belonging to the registered users group or a subgroup of it gains post and read privileges on all forums of the public forums category or a subcategory of it.

Object level permissions example

  # Assuming setup as in the above examples

  class Category < ActiveRecord::Base
    acts_as_nested_set
    acts_as_access_group
    has_many :forums
  end

  class Forum < ActiveRecord::Base
    belongs_to :category
    acts_as_access_object :grouped_by => :category
    privilege_const_set 'READ' => 'read postings in forum', 
                         'POST' => 'reply to threads in a forum'
  end

  # assume there is a forum 'speakers corner' assigned to the category 'public'.

  acl = ActiveAcl::Acl.create :section => ActiveAcl::AclSection.create(:description => 'forum')

  acl.allow = true
  acl.requester_groups << registered_users
  acl.target_groups << Category.find_by_name('public')

  acl.privileges << Forum::READ
  acl.privileges << Forum::POST

  acl.save

  speakers = Forum.find_by_name('speakers corner')

  john.has_privilege?(Forum::READ, :on => speakers) #=> true
  john.has_privilege?(Forum::POST, :on => speakers) #=> true
  anonymous.has_privilege?(Forum::READ, :on => speakers) #=> false

There is currently no advanced documentation for this plugin.