# auth-assistant #

Provides assistance for setting up an auth solution using devise and cancan auth frameworks.

## Installation and configuration ##

This gem has been designed for Rails 3 only.

Insert `gem 'auth-assistant'` in your Gemfile
Run `$ bundle install`

The gem should automatically configure itself with Rails after you run the `config` generator (see below). 

`$ rails g auth_assist:config NAME` where NAME is the name of the role strategy to be used.

To make the extra authentication view helpers accessible from your views

# app/helpers/application_helper.rb

module ApplicationHelper       
  auth_assist_helpers
end

## Permits ##

Authorization is setup by designing permits for each can of role to do certain actions.
The config generator generates a default permits.rb file in /lib

Please see "cancan 1.1 wiki":http://wiki.github.com/ryanb/cancan/upgrading-to-11 for more options 
you can use in designing your Permits. The 'owns' convenience method provided, now uses the new hash option so it
is also available in the controller using fx:

`Book.accessible_by(current_ability)` 

Example:
<pre>
module RolePermit
  class Moderator
    def initialize(ability)
      super
    end

    def permit?(user)
      super
      return if !user.role?(:moderator)
      can :read, :all    
      # can manage comment instance if 'user' field on instance points to this user, marking ownership
      user.owns(Comment) 

      # override default 'user_id' field to use 'owner' as foreign key to user.id  
      user.owns(Book, :author)       
    end  
  end
end
</pre>

## View helpers ##

Currently the view helpers only target use with devise and cancan.
The default labels are always loaded from the `auth_assist` locale file, which is generated by the `config` generator.

### Rest link helpers ###

Display a link (anchor tag) for a given object only if the current user has permission to execute that action.

* show_link or read_link
* edit_link or update_link
* create_link or new_link
* destroy_link or delete_link

Each Rest helper method takes an object for which to create the link. Optionally provide a label as the second argument. 

Example usage:

<%= create_link project %>
<%= create_link project, 'Create new project' %>

### Session link helpers ###

Show links for performing user authentication and registration actions 

* log_out_link or sign_out_link
* log_in_link or sign_in_link  

Each of these methods take an optional options hash. 
If no role option given, they default to create link for basic 'user' role.

Example usage:

<%= log_out_link %> 
<%= log_out_link :label => 'Log me out' %>
<%= log_out_link :role => 'admin', :label => 'Log me out' %>


### Registration link helpers ###

Show links for performing user authentication and registration actions 

* register_link or sign_up_link    
* edit_profile_link or edit_registration_link   

Each of these methods take an optional options hash. 
If no role option given, they default to create link for basic 'user' role.

Example usage:

<%= register_link %> 
<%= register_link :label => 'Register me' %>
<%= register_link :role => 'admin', :label => 'Register me' %>

### Registration Menu item helpers ###

Show menu links for registration conditionally

* edit_user_menu_item or edit_registration_menu_item   
* register_menu_item or sign_up_menu_item

1) only shown if user is currently logged in
2) only shown if user is NOT currently logged in (and hence already registered)

Example usage:

ul.menu
  <%= register_menu_item %> 

### Session Menu item helpers ###

Show menu links for session operations conditionally

* logout_menu_item or sign_out_menu_item 
* login_menu_item or sign_in_menu_item 
                                      
1) only shown if user is currently logged in
2) only shown if user is NOT currently logged in

ul.menu
  <%= login_menu_item %> 
  <%= logout_menu_item %> 


## Block helpers ##

Execute block if user is logged in (or not logged in)
* user_block
* not_user_block

Execute block if user is logged and is admin (or not admin)
* admin_block
* not_admin_block

Execute block if ip is localhost (or not localhost)
* localhost_block
* not_localhost_block
  
Execute block if role is included in list of roles (or not)
* roles_block
* not_roles_block

## Block area helpers ##

Create div.user 'area' and execute block if user is logged in as a user (or not) 

* user_area
* not_user_area

Create div.admin 'area' and execute block if user is admin (or not admin)

* admin_area
* not_admin_area

Example:
<pre>
<% admin_area do %> 
  ul.admin_menu
  ...

If logged in as admin, results in:

div.admin
  ul.admin_menu  
   ...
</pre>

## Roles block area helpers ##

Creates are if role is one included in list of roles (or not)

* roles_area
* not_roles_area

Example:
<pre>
<% roles_area 'admin, 'editor', :class => 'special' do %> 
  ul.admin_menu
  ...
  
If logged in as either 'editor' or 'admin', results in:

div.special
  ul.admin_menu  
   ...
    
</pre>

## Misc helpers ##

* user? - 
* admin?
* role?
* localhost?

Examples
<pre>     
<%= current_user.username if user? %>
<%= "Admin: #{current_user.username}" if admin? %>  
<%= "Special user!" if role?('admin', 'reviewer') %>  
<%= "Running on localhost!" if localhost? %>  
</pre>  

## Generators ##

The following generators are available 

* config - configure with new strategy
* clear - clear existing strategy
* views - generate partials for use in views

### Config Generator ###

The `config` generator generates a configuration initializer file for setting up `auth_assistant` to use a particular role strategy.

`$ rails g auth_assistant:config NAME`

NAME is the name of a role strategy. 

Strategies with a single role for each user
* admin_field
* role_field
* role_assignment

Strategies with multiple roles for each user
* roles_field
* roles_mask
* multi_role_assignment

Currently role groups are not supported. Feel free to provide an add-on to support this or integrate with an existing 'role group' solution.  

Example usage:

$ rails g auth_assist:config admin_field

Also ensure devise is setup and configured

$ rails g auth_assist:config roles_mask --devise

To also create an administrator model using STI to inherit and override the basic user strategies

$ rails g auth_assist:config roles_field --administrator

To ensure a user model migration is generated

$ rails g auth_assist:config role_field --migration


### Clear Generator ###

The `clear` generator removes any existing strategy file and optionally generates a migration to remove any tables and fields related to the existing role strategy.
This allows you to easily change role strategy by first running the `clear` generator and then the `config` generator with a new strategy.

`$ rails g auth_assist:clear NAME`                              

Example usage:

`$ rails g auth_assist:clear role_field`                              

### Views Generator ###

The `views` generator generates views (partials) for use with Menus. 

`$ rails g auth_assistant:views` 

Create HAML views

`$ rails g auth_assist:views --template_engine haml'

Example usage:
<pre>
  ul.menu
    render 'auth_assist/login_items'                              
    render 'auth_assist/registration_items'

  ul.admin_menu_
    render 'auth_assist/admin_login_items'
</pre>

== Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.