RoleModel is the framework agnostic, efficient and declarative way to do user roles. http://rdoc.info/github/martinrehfeld/role_model/master/frames
Find a file
2010-10-10 15:39:20 +02:00
lib refactoring: use .mask_for in #roles= 2010-10-10 15:33:59 +02:00
spec support most Set methods on #roles 2010-10-10 15:25:47 +02:00
.document Initial commit to role_model. 2010-05-24 21:50:46 +02:00
.gitignore Initial commit to role_model. 2010-05-24 21:50:46 +02:00
LICENSE Initial commit to role_model. 2010-05-24 21:50:46 +02:00
Rakefile configure rcov scope 2010-05-30 00:36:56 +02:00
README.rdoc add hint on #delete to README 2010-10-10 15:38:21 +02:00
role_model.gemspec Regenerated gemspec for version 0.6.0 2010-10-10 15:39:20 +02:00
VERSION Version bump to 0.6.0 2010-10-10 15:39:09 +02:00

= RoleModel

RoleModel is the framework agnostic, efficient and declarative way to do
(user) roles. Assigned roles will be efficiently stored as a bitmask
directly into your model within an configurable attribute.

It works like this:

  # given a User class with a roles_mask attribute
  require 'rubygems'
  require 'role_model'
  
  class User
    attr_accessor :roles_mask # in real life this would be an persisted attribute
    
    include RoleModel
    
    # optionally set the integer attribute to store the roles in,
    # :roles_mask is the default
    roles_attribute :roles_mask
    
    # declare the valid roles -- do not change the order if you add more
    # roles later, always append them at the end!
    roles :admin, :manager, :author
  end
  
  #
  # Test drive (check the RDoc or source for additional finesse)
  #
  
  >> u = User.new
  => #<User ...>
  
  # role assignment
  >> u.roles = [:admin]  # ['admin'] works as well
  => [:admin]
  
  # adding roles (remove via delete or re-assign)
  >> u.roles << :manager
  => [:admin, :manager]
  
  # querying roles...
  
  # get all valid roles that have been declared
  >> User.valid_roles
  => [:admin, :manager, :author]
  
  # ... retrieve all assigned roles
  >> u.roles # aliased to role_symbols for DeclarativeAuthorization
  => [:admin, :manager]
  
  # ... check for individual roles
  >> u.has_role? :author  # has_role? is also aliased to is?
  => false
  
  # ... check for multiple roles
  >> u.has_any_role? :author, :manager  # has_any_role? is also aliased to is_any_of?
  => true
  
  >> u.has_all_roles? :author, :manager  # has_all_roles? is also aliased to is?
  => false
  
  # see the internal bitmask representation (3 = 0b0011)
  >> u.roles_mask
  => 3
  
  # see the role mask for a certain role(s)
  >> User.mask_for :admin, :author
  => 5

Once you have included RoleModel, your model is perfectly fit to be used
together with a role-based authorization solution, such as
http://github.com/ryanb/cancan or
http://github.com/stffn/declarative_authorization .

== Installation

  gem install role_model

== Reasoning

Whenever I introduce a role-based authorization scheme into a project, the
code gets coupled somehow to the available roles. So it usually does not make
any sense to have a separate Role model stored within the database. This Role
model will contain a predefined set of roles anyhow -- changing that set will
need to be reflected within the authorization code. Putting the available
roles right into the model that actually uses them, makes things much easier
and efficient.

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

== Credits

RoleModel is an implementation of the Role Based Authorization scheme
proposed by Ryan Bates
(http://wiki.github.com/ryanb/cancan/role-based-authorization).

== Copyright

Copyright (c) 2010 Martin Rehfeld. See LICENSE for details.