Roles for Active Record

This is an Active Record implementation of the Roles generic API Please also see the Roles generic README

Roles lets you add a role strategy of choice to your user model. Roles supports strategies with either an inline attribute on user or a separate Role model (see below).

Install

gem install roles_active_record

Install in Rails app

Insert in Gemfile:

gem 'roles_active_record'

Run $ bundle install from terminal

Alternatively install using Cream

Role strategies

The following Role strategies are available for Active Record:

Inline attribute on User

admin_flag
roles_mask
role_string

These strategies all use an inline attribute on the User model.

Reference to Role

many_roles
one_role

These strategies use a separate Role model (class and table).

Role strategy configuration

The following demonstrates some examples of role strategy configuration.

Strategy: admin_flag

class User < ActiveRecord::Base    
  include Roles::ActiveRecord 
    
  strategy :admin_flag, :default
  valid_roles_are :admin, :guest
  
  def initialize attributes = {}
    super
    add_role default_role
  end  
end

Here the initializer initially sets the role of the user tothe default_role, which is the available role matching the class name (or nil in case no match)

Strategy: one_role

For strategies that use a separate Role model you must call the class method #role_class with the name of the role class

class Bruger < ActiveRecord::Base
  include Roles::ActiveRecord 

  strategy :one_role, :role_class => :rolle
  valid_roles_are :admin, :guest
end

Strategy: many_roles

Both the Role class and join class between User and Role can be customized using options

class Bruger < ActiveRecord::Base
  include Roles::ActiveRecord 

  strategy :one_role, :role_class => :rolle, :user_role_class => :bruger_rolle
  valid_roles_are :admin, :guest
end

Default Role classes

The default role classes can currently be included by:

One role:

require 'roles_active_record/one_role'

Many roles:

require 'roles_active_record/many_roles'

Note: These files will automatically be included when needed under normal conditions.

Roles generators

The gem includes these Rails 3 generators:

active_record:roles
active_record:roles_migration

Roles generator

Let you populate a User model with a given role strategy

Example: Apply Role strategy admin_flag to the User and make the default roles :admin and :guest available

$ rails g active_record:roles User --strategy admin_flag

Example: Apply Role strategy role_string to the User and make the roles :admin, :guest and :author available

$ rails g active_record:roles_migration User --strategy role_string --roles author

Example: Apply Role strategy one_role to the User model with roles :user, :special and :editor

$ rails g active_record:roles_migration User --strategy one_role --roles user special editor --no-default-roles

Example: Apply Role strategy many_role to the User model with default roles and customizing role class names to BrugerRolle and Rolle

$ rails g active_record:roles_migration User -s one_role -r user editor -rc Rolle -urc BrugerRolle

For the strategies one_role and many_roles the generator also generates the Role and UserRole classes in the app/models dir. If you customize the names of these classes (using generator arguments), the customized classes will be generated and “linked up” correctly (with has and belongs_to statements).

Roles migration generator

In case you only want to generate Role migrations.

Example: admin_flag Role strategy

$ rails g active_record:roles_migration User --strategy admin_flag

Create reverse migration

$ rails g active_record:roles_migration User --strategy admin_flag --reverse

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.