mirror of
https://github.com/Fishwaldo/role_model.git
synced 2025-03-15 11:32:04 +00:00
131 lines
4.1 KiB
Text
131 lines
4.1 KiB
Text
= 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 a 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 # just for demo purposes
|
|
# in real life this would usually be a persistent attribute,
|
|
# e.g. if your User model is persisted in a SQL-DB add an integer
|
|
# column named roles_mask to your users table -- just remove/replace
|
|
# above attr_accessor line with whatever is needed for your
|
|
# persistence solution
|
|
|
|
include RoleModel
|
|
|
|
# if you want to use a different integer attribute to store the
|
|
# roles in, set it with roles_attribute :my_roles_attribute,
|
|
# :roles_mask is the default name
|
|
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!
|
|
#
|
|
# Set dynamic: false to skip creating the dynamic methods for the roles.
|
|
roles :admin, :manager, :author, prefix: "is_"
|
|
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
|
|
>> u.roles << :manager
|
|
>> u.roles.add(:manager)
|
|
>> u.manager = true # if dynamic is enabled (by default) or...
|
|
>> u.is_manager = true # If :prefix => "is_"
|
|
=> [:admin, :manager]
|
|
|
|
# deleting roles
|
|
>> u.roles.delete(:manager)
|
|
>> u.manager = false # if dynamic is enabled (by default) or...
|
|
>> u.is_manager = false # If :prefix => "is_"
|
|
=> [:admin]
|
|
|
|
# querying roles...
|
|
|
|
# get all valid roles that have been declared
|
|
>> User.valid_roles
|
|
=> [:admin, :manager, :author]
|
|
|
|
# ... retrieve all assigned roles
|
|
>> u.roles # also: u.role_symbols for DeclarativeAuthorization compatibility
|
|
=> [:admin, :manager]
|
|
|
|
# ... check for individual roles
|
|
>> u.has_role? :author # has_role? is also aliased to is?
|
|
=> false
|
|
|
|
# ... check for individual roles with dynamic methods (set dynamic: false to disable)
|
|
>> u.author? # Or...
|
|
>> u.is_author? # If :prefix => "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 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.
|