Clearance

Simple, complete Ruby web app authentication.

We have clearance, Clarence.

Gem installation (Rails 2.1+)

In config/environments/test.rb:

config.gem ‘mocha’ config.gem ‘thoughtbot-shoulda’, :lib => ‘shoulda’, :source => “http://gems.github.com” config.gem ‘thoughtbot-factory_girl’, :lib => ‘factory_girl’, :source => “http://gems.github.com”

In config/environment.rb:

config.gem “thoughtbot-clearance”, :lib => ‘clearance’, :source => ‘http://gems.github.com’

Then:

rake gems:install rake gems:unpack

Generator

In a greenfield application, just run the generator:

script/generate clearance

This will create:

app/controllers/confirmations_controller.rb app/controllers/passwords_controller.rb app/controllers/sessions_controller.rb app/controllers/users_controller.rb app/models/user.rb app/models/user_mailer.rb app/views/confirmations/new.html.erb app/views/passwords/edit.html.erb app/views/passwords/new.html.erb app/views/sessions/new.html.erb app/views/user_mailer/change_password.html.erb app/views/user_mailer/confirmation.html.erb app/views/users/_form.html.erb app/views/users/edit.html.erb app/views/users/new.html.erb test/functional/confirmations_controller_test.rb test/functional/passwords_controller_test.rb test/functional/sessions_controller_test.rb test/functional/users_controller_test.rb test/unit/user_mailer_test.rb test/unit/user_test.rb

Add the corresponding Clearance module for any file(s) you don’t want to override. They are namespaced exactly like the directory structure of a Rails app:

app/models/user.rb already exists. include Clearance::App::Models::User

Tests

The tests use Shoulda >= 2.0.4 and Factory Girl. You should create a User Factory:

Factory.sequence :email do |n| “user#[email protected]” end Factory.define :user do |user| user.email { Factory.next :email } user.password “password” user.password_confirmation “password” end

In test/test_helper.rb:

class Test::Unit::TestCase self.use_transactional_fixtures = true self.use_instantiated_fixtures = false include Clearance::Test::TestHelper end

Controllers

In app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base helper :all protect_from_forgery include Clearance::App::Controllers::ApplicationController end

Migration

The generator will create a migration for you call [timestamp]_create_users.rb in you db/migrate directory. Please feel free to add field in the migrate before running rake db:migrate .

Routes

map.resources :users map.resource :session map.resources :users, :has_one => :password map.resources :users, :has_one => :confirmation map.resources :passwords map.register ‘/register’, :controller => ‘users’, :action => ‘new’ map.login ‘/login’, :controller => ‘sessions’, :action => ‘new’ map.logout ‘/logout’, :controller => ‘sessions’, :action => ‘destroy’

Environments

In config/environments/test.rb and config/environments/development.rb:

HOST = “localhost”

In config/environment.rb:

DO_NOT_REPLY = “[email protected]” PROJECT_NAME = “my_app_name”

Sessions Handling

One identified (through new_session_path), the logged in user is available through the current_user variable. Therefore, if you have a menu :

= link_to “Identification”, new_session_url | = link_to “Inscription”, new_user_url

You can test if the user has logged :

-if current_user Welcome =link_to #current_usercurrent_user.email, logout_path -else = link_to “Identification”, new_session_url | = link_to “Inscription”, new_user_url

User account

Since User is a RESTful resource, you can use the current_user route directly :

-if current_user Welcome =link_to current_user.email, current_user

Be sure to implement an edit action in your users controller.

Logout

If you have used the routes above, you’re created a direct route to logout :

=link_to “Click here to logout”, logout_path

Authors

  • thoughtbot, inc.
  • Dan Croak
  • Jason Morrison
  • Mike Burns
  • Josh Nichols
  • Mike Breen