= has_roles

+has_roles+ demonstrates a reference implementation for handling role management.

== Resources

API

* http://api.pluginaweek.org/has_roles

Bugs

* http://pluginaweek.lighthouseapp.com/projects/13277-has_roles

Development

* http://github.com/pluginaweek/has_roles

Source

* git://github.com/pluginaweek/has_roles.git

== Description

One of the easiest and most straightforward techniques for adding role management
and authorization to specific parts of your application is restricting usage on
controller/action-basis.  Each role defined in your system is mapped to one or
more permissions.  Each permission is a combination of a controller and action.

== Usage

Note that this is a reference implementation and, most likely, should be
modified for your own usage.

=== Adding permissions

To add permissions, you can either define your own Permission model or create
an initializer like so:

config/initializers/role_management:
  Permission.create :id => 2, :controller => 'admin/stats'
  Permission.create :id => 3, :controller => 'comments', :action => 'create'
  ...

=== Adding/Updating roles

To add or update roles, you can either define your own Role model or create an
initializer like so:

config/initializers/roles.rb:
  # Edit the default role called "administrator"
  Role[:administrator].permissions << 'admin/stats/'
  
  # Create a new role called "developer"
  Role.create :id => 2, :name => 'developer', :permissions => %w(
    comments/create
    admin/stats/
  )

=== Default Permissions/Roles

By default, the following permissions are define:
* application - Permission for accessing any part of the application

By default, the following roles are defined:
* admin - An administrator with the default permissions

You can remove the default permissions/roles by adding the following to your
initializer:

config/initializers/roles.rb:
  Role.destroy_all
  Permission.destroy_all
  ...

=== Checking a user's authorization

Below is an example of checking a user's authorization for a url before displaying
information:

app/views/layouts/application.rhtml:

  <% if authorized_for?(:controller => 'admin/users') %>
  <p>Read to start administering your website?</p>
  <% end %>

== Testing

Before you can run any tests, the following gem must be installed:
* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]

To run against a specific version of Rails:

  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails

== Dependencies

* Rails 2.1 or later
* acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration]
* plugins_plus[http://github.com/pluginaweek/plugins_plugins] (optional if app files are copied to your project tree)