No commit activity in last 3 years
No release in over 3 years
Roles solution for active-record-backed Rails 3 applications
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

~> 0.9
~> 2.8
~> 1.3
 Project Readme

Roleable

Build Status

A flexible roles solution for active-record-backed Rails 3 applications. Allows for multiple roles scoped to instances of any model, as well as global roles (admin, for example).

Roleable is designed to be ultra simple and obvious, letting you build upon it to satisfy your needs. It is also designed to be efficient: using database indices, and well-crafted queries so that it can handle a huge number of roles.

Installation

Add this line to your application's Gemfile:

gem 'roleable'

And then execute:

$ bundle

Run the generator to create the Role and AppliedRole models, migrations, and a configuration initializer:

$ rails g roleable:install

And then run the migrations:

$ rake db:migrate

(This will create the roles and applied_roles tables, together with the appropriate database indices.)

Setup

Include Roleable::Subject into your subject model, e.g.:

class User < ActiveRecord::Base
  include Roleable::Subject
  ...
end

Include Roleable::Resource into any models you want to relate a subject role to (resource), e.g.:

class Page < ActiveRecord::Base
  include Roleable::Resource
  ...
end

Usage

Subject

Add a role:

# global
user.add_role(:admin)

# resource-scoped
user.add_role(:editor, page)

Remove a role:

# global
user.remove_role(:admin)

# resource-scoped
user.remove_role(:editor, page)

Query a role:

# global
user.has_role?(:admin)

# resource-scoped
user.has_role?(:editor, page)

Find the resources of a given class for which a user has a given role:

user.resources_with_role(:editor, Page)

Find the resource of a given class for which a user has any of a list of roles:

user.resources_with_role([:editor, :author], Page)

Find a user's roles for a given resource:

user.roles_for_resource(page)

Or, all the global roles for a user:

user.roles_for_resource(nil)

Resource

Find subjects (users) with a given role:

page.subjects_with_role(:editor)

Find subjects matching any of a list of roles:

page.subjects_with_role([:editor, :author])

Customization

By default, roleable assumes that your subject model is called User. You can customize this by modifying the generated configuration intializer located at config/initializers/roleable.rb, e.g.:

Roleable.configure do |config|
  config.subject_class_name = 'principle'
end

For more details check out the API documentation on rubydoc.info.

Requirements

Rails 3, ActiveRecord, Ruby >= 1.8.7

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request