devise_invitable

It adds support to devise for send invitations by email (it requires to be authenticated) and accept the invitation setting the password.

DeviseInvitable currently only support rails 3, if you want to use it with rails 2.3 you must install version 0.2.3

Installation

Install devise_invitable gem, it should install dependencies (such as devise and warden):

sudo gem install devise_invitable

Configure devise_invitable inside your app (and devise if you weren’t using them):

gem 'devise'
gem 'devise_invitable'

Basic Usage

Follow the walkthrough for devise with the following modifications.

Add t.invitable to the migration:

create_table :users do
  ...
  t.invitable
  ...
end
add_index :users, :invitation_token # for invitable

Add :invitable to the devise line in your model:

class User < ActiveRecord::Base
  devise ..., :invitable
end

If you are using devise :all, you can add :invitable to config.all in devise initializer:

Devise.setup do |config|
  ...
  config.all = [..., :invitable]
  ...
end

Model configuration

DeviseInvitable adds a new configuration option, :invite_for. It’s the time a invitation is valid for. Default value is nil, which means invitation doesn’t expire.

Configuring views

All of the views are packaged inside the gem. If you’d like to customize the views, invoke the the following generator and it will copy all views to your application:

# rails generate devise_invitable:views

Controller filters

It adds authenticate_resource! filter to restrict who can send invitations. You can override this method in your ApplicationController. Default behavior is require authentication of the same resource_name, so if you only have a model with devise it will allow to all authenticated users to send invitations.

You have to configure mailer as it’s required for confirmable and recoverable.

I18n

It uses two flash messages, :send_instructions and :updated, which are translated as other flash messages from devise.

Sending an invitation

To invite a user use invite class model. You must set email in the attributes hash:

User.invite!(:email => '[email protected]')

To accept an invitation with a token use accept_invitation! class model. You must set invitiation_token attribute, and you can include other attributes in the hash, which will be updated in the record.

User.accept_invitation!(:invitation_token => params[:invitation_token])

Invitations controller implement this. You can go to /users/invitation/new to send an invitation and an email will be sent with a link to accept the invitation with a URL like /users/invitation/accept?invitation_token=…

Adding Invitable to a running application

Define a migration to add invitable to your model:

change_table :your_table do |t|
  t.string :invitation_token, :limit => 20
  t.datetime :invitation_sent_at
  t.index :invitation_token
end

# Allow null encrypted_password and password_salt
change_column :your_table, :encrypted_password, :string, :null => true
change_column :your_table, :password_salt, :string, :null => true

Add :invitable to the devise line of your model, or to config.all in devise initializer if your model uses devise :all.

Override authenticate_resource! filter if you need to customize who can send invitations as it’s explained in controller filters section.

Contributors

Check them all at:

github.com/scambra/devise_invitable/contributors

Special thanks to github.com/rymai:“rymai” for rails3 support, his fork was a great help.

Note on Patches/Pull Requests

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.