Clearance is a Rails engine

Clearance is now a Rails engine… BLAOW!

Why

Clearance has served us well for many months. Our only complaints were shared by others:

• lots of includes
• too much generated code
• too many tests to maintain
• sometimes awkward to override functionality

With the re-institution of Rails engines in Rails 2.3, we decided to convert Clearance to engine. The process was relatively painless, the code is far cleaner, and we think we were able to scratch all our itches.

Philosophy

We highly recommend that you use the Cucumber features that come with Clearance to test the integration of the engine with your app:

script/generate clearance_features

You no longer run Clearance’s generated Shoulda & Factory Girl tests within your test suite. That code is unit tested internally. Use the Cucumber features to test integration. If and when you override functionality, write your own unit tests.

Read Mixing Cucumber with Test::Unit/Shoulda if you’re getting started with Cucumber and not using RSpec.

Overriding

We haven’t and probably won’t ever move Clearance beyond email and password authentication, despite frequent requests. We’re focused on “clean code that works” for the baseline authentication we’ve written over and over again for clients.

A huge part of “clean code that works” means that overriding Clearance needs to be painless. The change to an engine helps achieve that goal.

class UsersController < Clearance::UsersController
  def edit
    ...
  end
end

ActionController::Routing::Routes.draw do |map|
  map.resources :users
end

That’s it.

• Write your tests for whatever action you want to add or override.
• Subclass one of Clearance’s controllers (Users, Sessions, Passwords, and Confirmations).
• Update your routes (by default, the routes will point to the namespaced Clearance controllers).

The Royal Library of Alexandria

All knowledge pertaining to Clearance can be found on its Github wiki, where you’ll find such articles as:

• Upgrading to Rails engine
• Organization of modules, routes, & flashes
• Extending Clearance with usernames, admins, or invite codes

.. and much more.

Enjoy!