roles_active_record

h1. Roles for Active Record

This is an Active Record implementation of the "Roles generic API":https://github.com/kristianmandrup/roles_generic/wiki Please also see the "Roles generic README":https://github.com/kristianmandrup/roles_generic

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).

h2. Install

gem install roles_active_record

h3. Install in Rails app

Insert in Gemfile:

gem 'roles_active_record'

Run $ bundle install from terminal

Alternatively install using "Cream":http://github.com/kristianmandrup/cream

h2. Role strategies

The following Role strategies are available for Active Record:

h3. Inline attribute on User

• admin_flag
• roles_mask
• role_string

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

h3. Reference to Role

• many_roles
• one_role

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

h2. Role strategy configuration

The following demonstrates some examples of role strategy configuration.

h3. Strategy: admin_flag

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)

h3. 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

h3. Strategy: many_roles

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

h3. 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.

h2. Roles generators

The gem includes these Rails 3 generators:

• active_record:roles
• active_record:roles_migration

h3. 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).

h3. 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

h2. 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.

h2. Copyright

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.