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

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.

Copyright

Copyright © 2010 Kristian Mandrup. See LICENSE for details.