Generic Role strategies

Generic role strategies that share the same API and are easy to insert in any existing User model. Comes with a Rails 3 generator to instantly configure your Rails 3 app with a Role strategy of choice.

I have developed the following roles gems for popular ORMs that all support the same roles generic API.

Active Record - roles_active_record
DataMapper - roles_data_mapper
Mongoid - roles_mongoid
MongoMapper - roles_mongo_mapper)

Feel free to roll your own ORM extension for your favorite ORM!

Status update (12 sept, 2010)

Roles generic has now been refactored in order to tidy up the code base and make it even more generic, flexible and easy to extend. It should now work! Please let me know if you have any issues ;)

Install

gem install roles_generic

Usage

The library comes with the following role models built-in:

Inline roles (in User model):

admin_flag (Boolean flag - 'admin' or not)
role_string (String)
roles_string (Comma separated String - note: no role name must have a comma in its name!)
role_strings (Set of Strings)
roles_mask (Integer mask)

Using separate Role model:

one_role (relation to a Role model instance)
many_roles(Set of Role relationships)

Note: The following examples use RSpec to demonstrate usage scenarios.

Examples of configuring for the other strategies can be found on the wiki pages.

Example : admin_flag

Creates and uses a binary field 'admin_flag', which when true signals that this user is an administrator and otherwise a normal user.

  class User
    include Roles::Generic 

    attr_accessor :name, :admin_flag 

    role_strategy :admin_flag, :default

    roles :admin, :user

    def initialize name, *new_roles
      self.name = name
      self.roles = new_roles
    end 
  end

Example: Using an ORM

Data Mapper with persistent attributes :name and :admin_flag

  class User
    include Roles::Generic 
    include DataMapper::Resource

    property :name, Boolean
    property :admin_flag, Boolean

    role_strategy :admin_flag, :default

    roles :admin, :user

    def initialize name, *new_roles
      self.name = name
      self.roles = new_roles
    end 
  end

Note: I recommend using s specific ORM roles gem such as roles_data_mapper instead. But this approach might be a good starting point for developing a roles gem for an ORM that is not supported ;)

Role API

Instance methods

Has ALL of the given roles been assigned?

has_roles?(*roles) - alias: is?

Has ANY (at least ONE) of the given roles been assigned?

has_role? *roles - alias: has?

Is this a valid role? (can the role be found in list of valid roles?)

valid_role? role

Is this user the admin user (and user has no other roles)

admin? - short for - is?(:admin)

Class methods

roles - list of valid roles
roles_attribute - get the attribute where the role is stored on the user
roles_attribute= - set the role(s) attribute

Usage of API

  before :each do
    @admin_user = User.new 'Admin user', :admin
    @guest = User.new 'Guest', :guest
  end

  it "user 'Admin user' should have role :admin" do

    @admin_user.role.should   == :admin
    @admin_user.roles.should  == [:admin]      
    @admin_user.admin?.should be_true

    @admin_user.has_role?   (:user).should be_false

    @admin_user.has_role?   (:admin).should be_true
    @admin_user.is?         (:admin).should be_true
    @admin_user.has_roles?  (:admin).should be_true
    @admin_user.has?        (:admin).should be_true      

  end

  it "user Guest should have role :guest" do
    @guest.roles.should == [:guest]
    @guest.admin?.should be_false

    @guest.has_role?  (:guest).should be_true    
    @guest.has_role?  (:admin).should be_false
    @guest.is?        (:admin).should be_false

    @guest.has_roles? (:guest).should be_true
    @guest.has?       (:admin).should be_false
  end

  it "should set role of Guest user from :guest to :admin using roles=" do
    @guest.roles        = :admin      
    @guest.role.should == :admin           

    @guest.has_role?(:admin).should be_true      
  end

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

yoda / roles_generic