Skip to content

Commit

Permalink
updating README to point people to the wiki
Browse files Browse the repository at this point in the history
  • Loading branch information
Dan Croak committed Feb 24, 2009
1 parent d99025a commit 8917443
Showing 1 changed file with 4 additions and 183 deletions.
187 changes: 4 additions & 183 deletions README.textile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ Rails authentication for developers who write tests.

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

h2. Wiki

Most information regarding Clearance is on the "Github Wiki":http://wiki.github.com/thoughtbot/clearance.

h2. Integration with Suspenders

Clearance is based on the same conventions and tools as "Suspenders":http://github.com/thoughtbot/suspenders If you use it, you already have some configuration mentioned below.
Expand Down Expand Up @@ -45,77 +49,6 @@ 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.

h2. Modules

Clearance works by mixing behavior into tests, controllers, and models. For any file that you do not want to overwrite, include the corresponding Clearance module. They are namespaced exactly like the directory structure of a Rails app.

Application controller example:

class ApplicationController < ActionController::Base
include Clearance::App::Controllers::ApplicationController
end

User model example:

class User < ActiveRecord::Base
include Clearance::App::Models::User
end

User test example:

class UserTest < Test::Unit::TestCase
include Clearance::Test::Unit::UserTest
end

h2. The migration

The generator will also create a migration to add a "users" table and run it. If the table already exists in the database, the migration will just add fields and indexes that are missing and required by Clearance. If the migration fails, the generator will revert all changes back.

h2. Routes

Clearance will add these routes to your routes.rb:

map.resources :users, :has_one => [:password, :confirmation]
map.resource :session
map.resources :passwords

Please note that Clearance depends on root_url, so please make sure that it is defined to *something* in your config/routes.rb:

map.root :controller => 'users', :action => 'new'

h2. Environments

You need to define HOST constant in your environments files. In config/environments/test.rb and config/environments/development.rb it can be:

HOST = "localhost"

While in config/environments/production.rb it must be the actual host your application is deployed to because the constant is used by mailers to generate URLs in emails.

In config/environment.rb:

DO_NOT_REPLY = "donotreply@example.com"

h2. The flash

You will need to display the success, failure, and notice flash messages in your layout. We recommend creating an app/layouts/_flashes.html.erb partial similar to the _flashes partial in Suspenders:

<pre><code><div id="flash">
<% flash.each do |key, value| -%>
<div id="flash_<%= key -%>"><%= html_escape(value) %></div>
<% end -%>
</div></code></pre>

which is then rendered inside the body tag of your application layout:

<%= render :partial => 'layouts/flashes' -%>

h2. Tests

The tests use "Shoulda":http://thoughtbot.com/projects/shoulda >= 2.9.1 and "Factory Girl":http://thoughtbot.com/projects/factory_girl >= 1.2.0.

The generator will create a user factory in test/factories/clearance.rb unless
you have it defined somewhere else.

h2. Features

If you are using Cucumber on your application Clearance comes with a feature generator:
Expand All @@ -136,118 +69,6 @@ All of the files generated should be new with the exception of the features/supp
...
end

h2. Usage: basic workflow

Rails authentication with Clearance uses the standard approach thoughtbot and our clients have agreed upon.

Users sign up (UsersController) using an email address and a password (User model). They get an email (ClearanceMailer) with a confirmation link to confirm sign up (ConfirmationController).

Signed up and email confirmed users can sign in and out (SessionsController). If they forget their password, they request an email (ClearanceMailer) containing a link to change it (PasswordsController).

h2. Usage: actions which require an authenticated user

To protect your controllers with authentication add:

class ProtectedController < ApplicationController
before_filter :authenticate

The filter will ensure that only authenticated users can access the controller. If someone who's not signed in tries to access a protected action:

* the URL is stored in the session,
* the user is redirected to sign in page, and
* after successful authentication will be be redirected back to that URL.

h2. Usage: signed_in?, current_user

Clearance provides two methods that can be used in controllers, helpers, and views to check if current user is authenticated and get the actual user:

* signed_in?
* current_user

<pre><code><% if signed_in? -%>
Hello, <%= current_user.name %>!
<% else -%>
Please <%= link_to 'Sign in', new_session_path %>
<% end -%></code></pre>

h2. Usage: mass assignment

Please note that 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::App::Models::User
attr_accessible :first_name, :last_name
end

h2. Usage: when bad things happen to good users

Clearance is HTTP fluent. If someone tries to hack the URLs for passwords or confirmations actions, they will be met with a 403 Forbidden HTTP status code. Internally, the Rails app will raise a ApplicationController::Forbidden error. This is a custom error in Clearance.

Layman's 403 Forbidden definition:

"The request was a legal request, but the server is refusing to respond to it.
Unlike a 401 Unauthorized response, authenticating will make no difference."

h2. 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":http://www.sivarg.com/2009/01/clearance-coming-from-where-your-were.html for the tip):

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

h2. 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 in the SessionsController:

class SessionsController < ApplicationController
include Clearance::App::Controllers::SessionsController

private

def url_after_create
new_blog_post_path
end
end

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)

h2. Hooks: sign_user_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_user_in that you can overwrite with that logic. Be sure to call sign_in(user) at the end (and write tests!).

class ApplicationController < ActionController::Base
include Clearance::App::Controllers::ApplicationController

private

def sign_user_in(user)
# store current time to display "last signed in at" message
user.update_attribute(:last_signed_in_at, Time.now)
sign_in(user)
end
end

h2. Write your own tests with Clearance's helpers

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

<pre><code>context "when signed in on GET to new" do
setup do
@user = Factory(:email_confirmed_user)
sign_in_as @user
get :new
end
should_be_signed_in_as { @user }
end</code></pre>

h2. Authors

Clearance was extracted out of "Hoptoad":http://hoptoadapp.com. We merged the authentication code from two of thoughtbot's client's Rails apps. The following people have made significant contributions, suggestions, and generally improved the library. Thank you!
Expand Down

0 comments on commit 8917443

Please sign in to comment.