Roleable

Build Status

A flexible user-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 UserRole models and migrations:

$ rails g roleable:install

And then run the migrations:

$ rake db:migrate

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

Setup

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

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

Include Roleable::Resource into any models you want to relate a user 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 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 users with a given role:

page.users_with_role(:editor)

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