Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

User roles for active-record-backed Rails 3 applications.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .rspec
Octocat-spinner-32 .travis.yml
Octocat-spinner-32 CHANGELOG
Octocat-spinner-32 Gemfile
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 Rakefile
Octocat-spinner-32 roleable.gemspec
README.md

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
Something went wrong with that request. Please try again.