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)

• Active Record
• Data Mapper

Mongo DB

• Mongoid
• Mongo Mapper

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:

• Roles-Read-API
• Roles-Write-API
• Roles-Group-API

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.

Copyright

Copyright © 2010 Kristian Mandrup. See LICENSE for details.