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> Here the role names have been customized 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.