ruby script/plugin install http://svn.rails-engines.org/plugins/user_engine

Users
=========
Once you have logged in as an administrator, you can go to /user/list to get a list of all users. Here you can also create new users (/user/new) and edit the details of the users in your system.

If you edit a user (/user/edit_user/+id+), you can now not only change user details and passwords, but also specify which roles the user has.

Roles
=======
Three distinct Role objects are initially created when you bootstrap the UserEngine

* Guest, with permissions to login, signup and retrieve forgotten passwords
* User, with permissions to logout, to to /user/home, change passwords and edit their own information
* Admin, with permissions to edit all users, list users, edit all roles, edit permissions, and so on.

New roles can easily be created at /role/new, where you can select exactly which permissions this role should have. A similar interface is presented in /role/edit/+id+. For instance, if you have a ReportController with the actions +view+ and +edit+, you might create two new Roles - 'ReportViewer' and ReportEditor'. The only permissions the ReportViewer has will be report/view, and the only permission assigned to ReportEditor is similarly report/edit. You can now assign the ReportViewer role to as many users as will need to be able to view reports, but only give the ReportEditor to users who should also be able to edit reports.

It's worth noting that this point that if a user has the ability to edit other users (/user/edit_user), they will be able to assign Roles (including the Admin role) to anyone they please. Similarly, users who can edit roles (/role/edit) can add any permissions at all to any Role within the system. Therefore you (as the system administrator) must be *very* careful about allowing these permissions on any role other than Admin.

In general, you should not give normal users *any* permissions other than the default ones, and permissions to any controllers specific to *your* application.

Permissions
===========
While you can create permissions using the regular scaffold-style interface, it is better to avoid manually creating them if possible. Instead, a method is provided for automatically scanning your controllers and ensuring that there exists a Permission object for each controller-action pair. This method is Permission.sychronize_controllers (or just Permission.sync as a shorthand), and can be called either from the console, or as a rake task:

rake sync_permissions 

It may be worth noting that currently this method will deliberately *never* delete any permission objects from your system, even if the method is no longer present.

Helper methods
==============

The UserEngine provides several helpers which understand permissions and roles, to be used in your views. The two most important are outlined below.

link_if_authorized(controller, action)

link_if_authorized will produce a link to an action *only* if the currently logged-in user has permission to perform the given action. It can be passed options to show the text (without a link) if the user is not authorized, or to wrap the text in another HTML element (i.e an li element) if a link is to be produced.

authorized?(controller, action)

authorized? will simply return true or false to reflect the current user's authorization for the given action. This method can also take a block, which will only be performed if the user is authorized for the given action. In this manner you can control the display chunks of HTML or certain processing based on the permissions of the current user.

There is currently no advanced documentation for this plugin.