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

<code>gem install roles_active_record</code>

h3. Install in Rails app

Insert in Gemfile:

<code>gem 'roles_active_record'</code>

Run <code>$ bundle install</code> 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

<pre>class User < ActiveRecord::Base    
  include Roles::ActiveRecord 
    
  strategy :admin_flag, :default
  valid_roles_are :admin, :guest
end
</pre>

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

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

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

h3. Strategy: many_roles

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

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

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

h3. Default Role classes

The default role classes can currently be included by:

One role:

<code>require 'roles_active_record/one_role'</code>

Many roles:

<code>require 'roles_active_record/many_roles'</code>

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

<code>$ rails g active_record:roles User --strategy admin_flag</code>

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

<code>$ rails g active_record:roles_migration User --strategy role_string --roles author</code>

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

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

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

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

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

<code>$ rails g active_record:roles_migration User --strategy admin_flag</code>

Create reverse migration

<code>$ rails g active_record:roles_migration User --strategy admin_flag --reverse</code>

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.