README.rdoc

November 16, 2023 · View on GitHub

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