= has_roles

+has_roles+ provides simple role management based on controllers/actions.

== Resources

API

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

Wiki

* http://wiki.pluginaweek.org/Has_roles

Announcement

* http://www.pluginaweek.org

Source

* http://svn.pluginaweek.org/trunk/plugins/active_record/has/has_roles

Development

* http://dev.pluginaweek.org/browser/trunk/plugins/active_record/has/has_roles

== 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

=== Checking a user's authorization

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

app/views/layouts/application.rhtml:

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

=== Global authorization

You can define a global permission that will add access for all controllers by
defining a controller with the path 'application'.  See the test fixtures for
more information.

=== Running migrations

To migrate the tables required for this plugin, you can either run the
migration from the command line like so:

  rake db:migrate:plugins PLUGIN=has_roles

or (more ideally) generate a migration file that will integrate into your main
application's migration path:

  ruby script/generate plugin_migration has_roles

== Testing

Before you can run any tests, the following gems must be installed:
* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
* dry_validity_assertions[http://wiki.pluginaweek.org/Dry_validity_assertions]

== Dependencies

This plugin is a plugin+.  That means that it contains a slice of an
application, such as models and migrations.  To test or use a plugin+, you
must have the following plugins/gems installed:
* plugin_dependencies[http://wiki.pluginaweek.org/Plugin_dependencies]
* loaded_plugins[http://wiki.pluginaweek.org/Loaded_plugins]
* appable_plugins[http://wiki.pluginaweek.org/Appable_plugins]
* plugin_migrations[http://wiki.pluginaweek.org/Plugin_migrations]

Instead of installing each individual plugin+ feature, you can install them all
at once using the plugins+[http://wiki.pluginaweek.org/Plugins_plus] meta package,
which contains all additional features.