README.md

Roleable

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