Usage

Write your own tests with Clearance’s helpers

sign_in_as, sign_out, should_deny_access and more helpers are available in your test suite. Look in vendor/gems/clearance/shoulda_macros for the full list.

context "when signed in on GET to new" do
  setup do
    @user = Factory(:email_confirmed_user)
    sign_in_as @user
    get :new
  end
  should_respond_with :success
end

Authenticate users for controller actions

If you want to authenticate users for a controller action, use the authenticate method in a before_filter.

class WidgetsController < ApplicationController
  before_filter :authenticate

  def index
    @widgets = Widget.all
  end
end

Mass assignment

All User attributes except email, password and password_confirmation are protected from mass assignment by default. Use attr_accessible to enable it for your custom attributes.

class User < ActiveRecord::Base
  include Clearance::User
  attr_accessible :first_name, :last_name
end

Hooks: return_to parameter

To specify where to redirect a user (say you want to have a sign in form on every page and redirect the user to the same page) after he/she signs in, you can add a “return_to” parameter to the request (thanks to Phillippe for the tip):

<% form_for :session, :url => session_path(:return_to => request.request_uri) do |form| %>

Hooks: url_after_create, url_after_update, url_after_destroy

Actions that redirect (create, update, and destroy) in Clearance controllers are customizable. If you want to redirect a user to a specific route after signing in, overwrite the “url_after_create” method:

class SessionsController < Clearance::SessionsController
  private
    def url_after_create
      new_blog_post_path
    end
end

You’ll also need to add an appropriate declaration in your config/routes.rb file to tell your app to use your overriding controller instead of the controller inside Clearance’s engine. Following the example above, to override Clearance’s sessions controller, you’d add this to your config/routes.rb file:

map.session 'session', :controller => 'sessions', :action => 'create'

There are similar methods in other controllers as well:

• UsersController#url_after_create (sign up)
• SessionsController#url_after_create (sign in)
• SessionsController#url_after_destroy (sign out)
• PasswordsController#url_after_create (password request)
• PasswordsController#url_after_update (password)
• ConfirmationsController#url_after_create (confirmation)

Hooks: sign_in

Say you want to add a last_signed_in_at attribute to your User model. You would want to update it when the User signs in.

Clearance has a method named sign_in that you can overwrite with that logic. Be sure to write tests!

class ApplicationController < ActionController::Base
  include Clearance::Authentication
  
  private
    def sign_in(user)
      # store current time to display "last signed in at" message
      user.update_attribute(:last_signed_in_at, Time.now)
      super user
    end
end