role_model/README.rdoc
2010-05-29 23:27:11 +02:00

96 lines
2.7 KiB
Text

= RoleModel
Ever needed to assign roles to a model, say a User, and build conditional
behaviour on top of that?
Assigned roles will be stored as a bitmask in an configurable attribute
(default: <tt>roles_mask</tt>). Here's how to get started:
# 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 / DB-column
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
#
>> u = User.new
=> #<User ...>
# role assignment
>> u.roles = [:admin] # ['admin'] works as well
=> [:admin]
# adding roles
>> u.roles << :manager
=> [:admin, :manager]
# quering roles...
# ... retrieve all assigned roles
>> u.roles # aliased to role_symbols for DeclarativeAuthorization
=> [:admin, :manager]
# ... check for individual roles
>> u.has_role? :author
=> false
>> u.is_a? :admin # has_role? is aliased as is_a?
=> true
# see the internal bitmask representation (3 = 0b0011)
>> u.roles_mask
=> 3
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.