Invites and Clearance

This page contains code for Rails 2. If you want to use invites in Clearance for Rails 3, see Invites and Clearance (Rails 3).

Clearance doesn’t support invitation codes but they are easily added.

The techniques described here were developed while building s3analytics.com and will cover:

• Why invitation codes are useful
• Requiring an invite code
• Testing the User creation process

Why invitation codes are useful

In layman’s terms:

Invitation codes are useful for controlling the number of accounts created in a new web service. This is especially important since it will allow a team to roll out fixes and enhancements and respond to user feedback in a timely fashion, ultimately delivering users the best possible experience.

By default, Clearance lets anyone sign up for a new account. The next two sections will describe how to override that behavior.

Requiring an invite code

Users require a redeemable Invite to successfully register an account.

1. Create an “invite” resource. In a Rails application, run:
$ ./script/generate scaffold invite

2. Open up the migration and add the following fields and indexes:

def self.up
  create_table :invites do |t|
    t.string :firstname
    t.string :lastname
    t.string :email
    t.string :invite_code, :limit => 40
    t.datetime :invited_at
    t.datetime :redeemed_at
    t.index [:id, :email]
    t.index [:id, :invite_code]
  end
end

In layman’s terms:
An Invite may only be redeemed once. It keeps track of when an Invite was delivered and when it was redeemed. See how I’ve further customized the Invite.

Run the migration:

$ rake db:migrate

3. Once we have the Invite model in place, we’ll need to modify the existing InvitesController to lockdown actions, send emails, and list invites.

Lockdown admin actions

Since we have the rule that anyone should be able to create Invites, but only Admins may modify or delete them, one quick and dirty way we can lock the controller down is with a before_filter, like so:

before_filter :access_for_admin, :except => [:new, :create]

Where the access_for_admin method contains logic that enforces an admin policy on a resource. i.e. it uses HTTP 401, or ensures a user has the correct ACL.

Sending emails

To send emails, we’ll need to add a few routes: send_invitation and redeem_invitation:

map.send_invitation '/send_invitation/:id', :controller => 'invites', :action => 'send_invitation'
map.redeem_invitation '/signup/:invite_code', :controller => 'users', :action => 'new'

Where the send_invitation action looks like this:

def send_invitation
  @invite = Invite.find(params[:id])
  @invite.invite!
  Mailer.deliver_invitation(@invite)
  flash[:notice] = "Invite sent to #{@invite.email}"
  redirect_to(invites_url)
end

And the Mailer invitation method looks like this:

def invitation(invite)
  from       DO_NOT_REPLY
  recipients invite.email
  subject    "Welcome to S3 Analytics"
  body       :invite => invite
end

And the corresponding HTML partial is a friendly email containing a URL to the invite redemption page:

<%= redeem_invitation_url(@invite.invite_code) %>

Listing invites

To list invites, we’re going to add an additional column to the index view on the InvitesController. In Haml:

%td
  - if invite.invited?
    Invited
  - else
    = link_to 'Invite', send_invitation_path(invite), :confirm => 'Send invitation? ', :method => :post

4. Once we have the emails in place, we’ll need to subclass Clearance::UsersController to support invitation based registrations. We do this by overriding the create action (See related Gist):

5. And finally, we’ll add a form which invites visitors to enter their name and email. I left this bit out since it’s pretty much a boilerplate Rails form helper.

Attribution

This idea was lifted from S3 Analytics and written up by Marc Chung.