Headstart

Headstart is an enhancement based on Blue Light Special which is a derivative from Thoughtbot’s Clearance gem.

In addition to the basic email and password authentication provided by Clearance, a default Blue Light Special installation includes:

optional support for authenticating with Facebook Connect, using mini_fb
a simple role system with built-in support for admin users
the ability for an admin to impersonate any other user
use of MadMimi for sending notification emails
delayed_job for sending emails in the background

a basic application layout and stylesheet

Setup

Note: Before Headstart can run, the database must be created, the database.yml configured, and permissions granted to the user. The ‘create-rails-dev-db’ gem does all this. Run it with ‘create-rails-dev-db’ within the Rails app first.

After installing the Headstart gem, require it in your Rails app and run the headstart generator.

In your config/environment.rb:

config.gem 'headstart'

Run the generators and migrate your database:

script/generate headstart
script/generate delayed_job
rake db:migrate

You’ll also want to take a look at Blue Light Special’s configuration options in config/headstart.yml.

Tests

Blue Light Special can optionally generate integration tests that cover all of its basic features. These tests require shoulda, factory_girl, webrat, and fakeweb. To install the tests:

script/generate headstart_tests

After the generator runs, you’ll see instructions for updating test/test_helper.rb to include some helper methods that the tests require. You can also use these helper methods in your own integration tests whenever you need to sign a user in or out.

Administration Interface

The final Blue Light Special generator builds a very simple administration interface for your app. This allows admins to manage and impersonate users, and it can be used as a starting point for building a more elaborate admin interface. If you’d like to generate the admin interface, run:

script/generate headstart_admin

This will generate your user admin controller and its integration test.

Mad Mimi

If you’d like an overview of Mad Mimi, check out the third part of this screencast. In order to get Blue Light Special working with Mad Mimi, you’ll need to sign up for an account at madmimi.com.

Your Mad Mimi account needs API access, so be sure to enable that during the signup process. The support people at Mad Mimi will manually authorize your account for API access. This usually happens within a few hours after you’ve signed up. Until your account is authorized, you’ll see HTTP errors when your Rails app attempts to send email.

After you’ve signed up and your API access has been approved, all you’ll need to do is put your Mad Mimi username and API key in config/headstart.yml.

Facebook Connect

To set up Facebook Connect, go to the Facebook developer page and create a new Facebook app. Since you’re only using this app for Facebook Connect, you can leave most of the fields blank. Be sure to give your app a name, and then head over to the Connect settings and set the Connect URL to point at your Rails app. In the Advanced section, you’ll need to set Email Domain to the domain from which you’ll be sending email messages.

After you’ve finished setting up your Facebook app, grab its API key and secret key and put them in config/headstart.yml.

To Build the Gem ==

rake gemspec

gem build headstart.gemspec

sudo gem install headstart.gem

gem push headstart-0.1.0.gem

gem yank headstart -v 0.1.0

Differences from Blue Light Special ==

MimiMailer was made optional. In some cases, like deploying on heroku, you won’t want to use MimiMailer templates, but instead regular mailer templates. Headstart does not use MimiMailer unless you’ve setup your login info for that service.
DelayedJob is now optional. You can turn off the use of delayed job, again in the case of deploying to Heroku for example where you do not want to pay the extra fees of using a background worker. In this case emails will be sent immediately and not queued.
The welcome email is not only suppressed if the email is already confirmed, but is also not sent if the user connects via Facebook. Since Facebook returns the email already, which presumably Facebook has already confirmed, Headstart marks the user as already confirmed.
Headstart adds back into Headstart, the email confirmation from Clearance. This is only used for non-facebook connect users
Added flash notice on creation of user
Using redirect_back_or in all cases so app using Headstart gem has an option of where to send the user
Added a facebook_logout method that facebook can call via its Post-Remove Callback, to remove user from app
Changed to user can still log in even though they haven’t confirmed their email (they just aren’t active)
The change password function was using the confirmation token instead of the password reset token in several spots
Implements www.modernizr.com/docs/