h1. Clearance

Rails authentication with email & password.

"We have clearance, Clarence.":http://www.youtube.com/v/mNRXJEE3Nz8

h2. Suspenders

Clearance is included in "Suspenders":http://github.com/thoughtbot/suspenders, which thoughtbot uses on all of our apps. We highly recommend you try it. Suspenders is the "King Gem" in our ecosystem, representating what we think the current state-of-the-art is in Rails development.

h2. Installation

Clearance is a Rails engine. It works with versions of Rails greater than 2.3.

In config/environment.rb:

<pre>
config.gem "thoughtbot-clearance",
  :lib     => 'clearance',
  :source  => 'http://gems.github.com',
  :version => '0.7.0'
</pre>

Vendor the gem:

<pre>
rake gems:install
rake gems:unpack
</pre>

Make sure the development database exists and run the generator:

<pre>
script/generate clearance
</pre>

A number of files will be created and instructions will be printed.

You may already have some of these files. Don't worry. You'll be asked if you want to overwrite them.

Run the migration:

<pre>
rake db:migrate
</pre>

h2. If you aren't on Suspenders, you aren't done

Define a HOST constant in your environment files.
In config/environments/test.rb and config/environments/development.rb it can be:

<pre>
HOST = "localhost"
</pre>

In production.rb it must be the actual host your application is deployed to.
The constant is used by mailers to generate URLs in emails.

In config/environment.rb:

<pre>
DO_NOT_REPLY = "donotreply@example.com"
</pre>

Define root_url to *something* in your config/routes.rb:

<pre>
map.root :controller => 'home'
</pre>

h2. Cucumber Features

As your app evolves, you want to know that authentication still works. thoughtbot's opinion is that you should test its integration with your app using "Cucumber":http://cukes.info/.

Run the Cucumber generator (if you haven't already) and Clearance's feature generator:

<pre>
script/generate cucumber
script/generate clearance_features
</pre>

All of the files generated should be new with the exception of the features/support/paths.rb file. If you have not modified your paths.rb then you will be okay to replace it with this one. If you need to keep your paths.rb file then add these locations in your paths.rb manually:

<pre>
def path_to(page_name)
  case page_name
   ...
  when /the sign up page/i
   new_user_path
  when /the sign in page/i
   new_session_path
  when /the password reset request page/i
   new_password_path
  ...
end
</pre>

h2. Formtastic views

We have begun standardizing our forms using "Formtastic":http://github.com/justinfrench/formtastic. We highly recommend trying it. It will make your Rails view life more interesting.

Clearance has another generator to generate Formastic views:

<pre>
script/generate clearance_views
</pre>

Its implementation is designed so that other view styles can be generated if the community wants it. However, we haven't needed them so you'll have to write the patch and send it back if you want other styles (such as Haml).

h2. Authors

Clearance was extracted out of "Hoptoad":http://hoptoadapp.com. We merged the authentication code from two of thoughtbot's clients' Rails apps and have since used it each time we need authentication. The following people have improved the library. Thank you!

Dan Croak, Mike Burns, Jason Morrison, Joe Ferris, Eugene Bolshakov, Nick Quaranto, Josh Nichols, Mike Breen, Marcel Görner, Bence Nagy, Ben Mabey, Eloy Duran, Tim Pope, Mihai Anca, Mark Cornick, Shay Arnett, Joshua Clayton & Mustafa Ekim.

h2. Questions?

Ask the "mailing list":http://groups.google.com/group/thoughtbot-clearance

h2. Suggestions, Bugs, Refactoring?

Fork away and create a "Github Issue":http://github.com/thoughtbot/clearance/issues. Please don't send pull requests.