Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Generic role model strategies sharing same API easy to insert in any model
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
wiki/strategies
.document
.gitignore
.rspec
Changelog.textile
Gemfile
LICENSE
README.textile
Rakefile
VERSION
roles_generic.gemspec

README.textile

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).

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.

Something went wrong with that request. Please try again.