Generic Roles

Generic Roles (or simply Roles) is a generic Roles API implementation that specific ORM Roles implementations can implement. This way you can easily change ORM and still keep using the same underlying API.

A Rails 3 generator is included that can configure an existing User model with a generic Role strategy of choice. Each ORM Roles implementation should have its own generator suited for that particular ORM.

Since Jan. 2011, Roles now includes a Group API that allows ordering roles into groups (see below).

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 to integrate it into my master. Thanks!

Roles ORM implementations

The following ORM specific Roles implementations are currently available

Relational Database (SQL)

Mongo DB

Couch DB

Simply Stored

Note:

The ‘simply_stored’ implementation is only partly complete (admin_flag strategy works). Feel free to roll your own implementation for your favorite ORM/Data store.

Install

gem install roles_generic

Role strategy configuration

The following demonstrates some examples of role strategy configuration.

Strategy: admin_flag

Example: Default model configuration:

class User
  include Roles::Generic 
    
  strategy :admin_flag
  valid_roles_are :admin, :guest
  ...
end

Strategy: one_role

Example: Customizing model names:

class Bruger
  include Roles::Generic 

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

Here the Role class is configured to be named ‘Rolle’ (Danish translation). If no :role_class options is passed, the default role class ‘Role’ is used (if the Role class is defined).

Note: The customizing of the Role class model is not yet complete. The generator and such still needs to be updated… Feel free to assist!

Roles generator

A Rails 3 generator is included to update an existing User model with a roles strategy and a set of valid roles. The Generic Roles generator doesn’t work for a persistent model. In that case use a dedicated implementation for the ORM (data store) used (see above).

Usage example

rails g roles_generic:roles --strategy admin_flag --roles guest admin

Role strategies

The following role strategies are built-in:

Inline roles (attribute in User model):

admin_flag (Boolean flag – ‘admin’ or not)
role_string (String)
roles_string (comma separated String)
role_strings (list of Strings)
roles_mask (Integer mask)

Separate Role model:

one_role (single relation to a Role model instance)
many_roles (multiple Role relationships)

Embedded Role model (Document stores only):

embed_one_role
embed_many_roles

Currently the embedded strategies have only been implemented for Mongoid.

See Roles strategy configuration for more info

Roles APIs

The full Roles API is described in these Wiki pages:

Using Roles Groups

The Group API allows roles to be grouped.

Example:

Say you have the admin roles:

Admin
Super admin

And the customer roles

Individual customer
Company customer

You might want to group them like this:


  User.add_role_group :customers => [:individual_customer, :company_customer]
  User.add_role_group :admins => [:admin, :super_admin]

Then you can handle any user with regards to his/her role group relationship like this:


  # do this only for users in the admin role group (user has either :admin or :super_admin role) 
  current_user.is_in_group? :admin do
    ...
  end

Expect this functionality to soon to be wrapped by Cream helper methods as well ;)

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.