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)
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.
gem install roles_generic
Role strategy configuration
The following demonstrates some examples of role strategy configuration.
Example: Default model configuration:
class User include Roles::Generic strategy :admin_flag valid_roles_are :admin, :guest ... end
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!
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).
rails g roles_generic:roles --strategy admin_flag --roles guest admin
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):
Currently the embedded strategies have only been implemented for Mongoid.
See Roles strategy configuration for more info
The full Roles API is described in these Wiki pages:
Using Roles Groups
The Group API allows roles to be grouped.
Say you have the admin roles:
- 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 © 2010 Kristian Mandrup. See LICENSE for details.