Usage

Add a role to a user

1. To define a global role:

    user = User.find(1)
    user.has_role "admin"
   

2. To define a role scoped to a resource instance

    user = User.find(2)
    user.has_role "moderator", Forum.first
   

3. To define a role scoped to a resource class

    user = User.find(3)
    user.has_role "moderator", Forum
   

4. Starting from rolify 2.1, grant is a method alias for has_role

    user = User.find(4)
    user.grant "moderator", Forum.last
   

Check roles

1. To check if a user has a global role:

    user = User.find(1)
    user.has_role "admin" # sets a global role
    user.has_role? "admin"
    => true
   

2. To check if a user has a role scoped to a resource:

    user = User.find(2)
    user.has_role "moderator", Forum.first # sets a role scoped to a resource
    user.has_role? "moderator", Forum.first
    => true
    user.has_role? "moderator", Forum.last
    => false
    user.has_role? "moderator"
    => false # returns false because the role is not global
    user.has_role? "moderator", :any
    => true # returns true because the user has at least one moderator role
   

3. To check if a user has a role scoped to a resource class:

    user = User.find(3)
    user.has_role "moderator", Forum # sets a role scoped to a resource class
    user.has_role? "moderator", Forum
    => true
    user.has_role? "moderator", Forum.first
    => true
    user.has_role? "moderator", Forum.last
    => true
    user.has_role? "moderator"
    => false
    user.has_role? "moderator", :any
    => true
   

4. A global role has an implicit role for all resources:

    user = User.find(4)
    user.has_role "moderator" # sets a global role
    user.has_role? "moderator", Forum.first
    => true
    user.has_role? "moderator", Forum.last
    => true
    user.has_role? "moderator", Forum
    => true
    user.has_role? "moderator", :any
    => true
   

5. Using dynamic shortcuts (read also #6)

    user = User.find(1)
    user.has_role "admin" # sets a global role
    user.is_admin?
    => true
    user.has_role "moderator", Forum.first
    user.is_moderator_of? Forum.last
    => false
   

6. To be able to use dynamic shortcuts, you need to enable it first in the initializer file:

    Rolify.dynamic_shortcuts = true if defined?(Rails::Server) == true || defined?(Rails::Console) == true
   

And to uncomment the extend Rolify::Dynamic line in the User class:

    extend Rolify::Dynamic

Multiple roles checking

1. Check if the user has ALL specified roles

    user = User.find(1)
    user.has_role "admin" # sets a global role
    user.has_role "moderator", Forum.first # sets a role scoped to a resource instance
    user.has_role "visitor", Forum # set a role scoped to a resource class
    user.has_all_roles? "admin", { :name => "moderator", :resource => Forum.first }, { :name => "visitor", :resource => Forum }
    => true
    user.has_all_roles? "admin", { :name => "moderator", :resource => Forum.last }
    => false
    user.has_all_roles? "god", { :name => "visitor", :resource => Forum }
    => false
   

2. Check if the user has ANY of specified role

    user = User.find(1)
    user.has_role "admin" # sets a global role
    user.has_role "moderator", Forum.first # sets a role scoped to a resource
    user.has_role "visitor", Forum # set a role scoped to a resource class
    user.has_any_role? "admin", { :name => "moderator", :resource => Forum.first }, { :name => "visitor", :resource => Forum }
    => true
    user.has_any_role? "admin", { :name => "moderator", :resource => Forum.last }
    => true
    user.has_any_role? "god", { :name => "visitor", :resource => Forum }
    => true
   

Remove a role from a user

1. Remove a global role

    user = User.find(1)
    user.has_no_role "admin"
    => true # if user got a admin role
   

2. Remove a role scoped to a resource instance

    user = User.find(2)
    user.has_no_role "moderator", Forum.first
    => true # if user got a moderator role on Forum.first
   

3. Remove a role scoped to a resource class

    user = User.find(3)
    user.has_no_role "moderator", Forum
    => true # if user got a moderator role on Forum or any instance of Forum
   

4. Starting from rolify 2.1, revoke is a method alias for has_no_role.

    user = User.find(4)
    user.revoke "moderator", Forum.first
   

Please note that:

• Trying to remove a global role whereas the user a role with the same name on a resource will remove that scoped role (whatever the scope is)
• Trying to remove a class scoped role whereas the user an instance scoped role with the same name on a resource will remove that instance scoped role
• Trying to remove a role scoped to a resource class whereas the user has a global role won't remove it
• Trying to remove a role scoped to a resource instance whereas the user has a global role won't remove it

Previous: Configuration