Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Roles for Active Record implementing the Roles generic API

This branch is even with kristianmandrup:rails_3_1

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
lib
spec
.document
.gitignore
.rspec
Changelog.textile
Gemfile
LICENSE
NOTES.textile
README.textile
Rakefile
VERSION
roles_active_record.gemspec

README.textile

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

You need help?

Please post questions in the rails-roles group.

If you have issues or bug reports, please post these as Issues on the github.
I recommend you try to fix any problems you might encounter by forking the project, implement the fix by writing specs
and make a pull request (so I can integrate the fix into my master). Thanks!

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.

Copyright

Copyright © 2010 Kristian Mandrup. See LICENSE for details.

Something went wrong with that request. Please try again.