Usage

Add a role to a user

1. To define a global role:

        user = User.find(1)
        user.add_role :admin

2. To define a role scoped to a resource instance

        user = User.find(2)
        user.add_role :moderator, Forum.first

3. To define a role scoped to a resource class

        user = User.find(3)
        user.add_role :moderator, Forum

4. Starting from rolify 2.1, grant is a method alias for add_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.add_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.add_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.add_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.add_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

Dynamic shortcuts

To be able to use dynamic shortcuts, make sure it's enable in the initializer file (config/initializer/rolify.rb):

Rolify 2.x and earlier

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

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

        extend Rolify::Dynamic

Rolify 3.x and later

        Rolify.configure do |c|
          c.use_dynamic_shortcuts
        end

that's it !

Usage

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

Multiple roles checking

1. Check if the user has ALL specified roles

        user = User.find(1)
        user.add_role :admin # sets a global role
        user.add_role :moderator, Forum.first # sets a role scoped to a resource instance
        user.add_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.add_role :admin # sets a global role
        user.add_role :moderator, Forum.first # sets a role scoped to a resource
        user.add_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.remove_role :admin
        => true # if user got a admin role

2. Remove a role scoped to a resource instance

        user = User.find(2)
        user.remove_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.remove_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 remove_role

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

Please note:

• 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

Resource role querying

Starting from rolify 3.0, you can search roles on instance level or class level resources.

1. Instance level

        forum = Forum.first
        forum.roles
        # => [ list of roles that are only binded to forum instance ]
        forum.applied_roles
        # => [ list of roles binded to forum instance and to the Forum class ]

2. Class level

        Forum.with_role(:admin)
        # => [ list of Forum instances that has role "admin" binded to it ] 
        Forum.with_role(:admin, current_user)
        # => [ list of Forum instances that has role "admin" binded to it and belongs to current_user roles ]
        
        Forum.find_roles
        # => [ list of roles that binded to any Forum instance or to the Forum class ]
        Forum.find_roles(:admin)
        # => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name ]
        Forum.find_roles(:admin, current_user)
        # => [ list of roles that binded to any Forum instance or to the Forum class with "admin" as a role name and belongs to current_user roles ]

Previous: Configuration