IMPORTANT: This fork is not maintained anymore, please use the official devise_invitable by @scambra instead!¶ ↑
It adds a module to Devise that allow authenticated resources to send invitations by email to others. Invited resources accept an invitation by setting their password.
This fork of DeviseInvitable only supports Rails ~> 3.0.0 and Devise ~> 1.1.2 Also, it is not distributed on RubyGems, so you’ll need to require this gem with the :git option of bundler in your Gemfile:
gem "devise", "~> 1.1.2" gem "devise_invitable", :git => "git://github.com/rymai/devise_invitable.git"
After you install DeviseInvitable and add it to your Gemfile, you need to run the generator:
rails generate devise_invitable:install
The generator will inject DeviseInvitable’s configuration options and you should take a look at it. When you are done, you are ready to add DeviseInvitable to any of your Devise models using the generator:
rails generate devise_invitable MODEL
Replace MODEL by the class name you want to add DeviseInvitable, like User, Admin, etc. This will add the :invitable flag to your model’s Devise modules. The generator will also create a migration file (if your ORM support them). Continue reading this file to understand exactly what the generator produces and how to use it.
Follow the walkthrough for Devise and after it’s done, follow this walkthrough.
Add :invitable to the Devise line in your model (we’re assuming here you already have a User model with some Devise modules):
class User < ActiveRecord::Base devise :database_authenticatable, :confirmable, :invitable end
Add t.invitable to your Devise model migration:
create_table :users do ... t.invitable ... end add_index :users, :invitation_token
or for a model that is already created, define a migration to add DeviseInvitable to your model:
change_table :users 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 :users, :encrypted_password, :string, :null => true change_column :users, :password_salt, :string, :null => true
DeviseInvitable doesn’t use attr_accessible or attr_protected, so be sure to define attributes as accessible or protected in your model.
If you don’t have the time to read more, or if you’d like to see how to integrate DeviseInvitable to an application, check the following example: example to come soon…
DeviseInvitable adds two configuration options:
* invite_for => The validity duration for an invitation. Default is 0, which means invitations doesn't expire. * validate_on_invite => Flag that can force the validation of the invited record on invitation. Default to false.
You can set those configuration options in the Devise initializer as follow:
# ==> Configuration for :invitable # Time interval where the invitation token is valid. # If invite_for is 0 or nil, the invitation will never expire. # Default: 0 # config.invite_for = 2.weeks # Flag that force a record to be valid before being actually invited. # Default: false # config.validate_on_invite = true
or directly as parameters to the devise method inside your Devise models:
devise :database_authenticatable, :confirmable, :invitable, :invite_for => 2.weeks
For details, see config/initializer/devise.rb (after you invoked the “devise_invitable:install” generator described above).
All the views are packaged inside the gem. If you’d like to customize the views, invoke the following generator and it will copy all the views to your application:
rails generate devise_invitable:views
You can also use the generator to generate scoped views:
rails generate devise_invitable:views users
Please be sure you have config.scoped_views = true in config/initializer/devise.rb! Please refer to Devise’s README for more information about views.
To send an invitation to a user, use the invite class method. You must set email in the parameters hash: You can also include other attributes in the hash. By default, the record will not be validated, see the Model configuration above if you want to validate the records before sending an invitation.
User.invite(:email => "new_user@example.com", :name => "John Doe") # => an invitation email will be sent to new_user@example.com
You can also use the invite instance method as follow:
User.new(:email => "new_user@example.com", :name => "John Doe").invite # => an invitation email will be sent to new_user@example.com User.find_by_invitation_token("oijd98q6yg28quwd98dwqo").invite # => an new invitation email will be sent to this user, the generated token will be different
To accept an invitation with a token use the accept_invitation class method. You must set invitation_token in the parameters hash. You can include other attributes in the hash (as in the update_attributes method for example).
User.accept_invitation(:invitation_token => params[:invitation_token], :password => "ad97nwj3o2", :name => "John Doe")
You can also use the accept_invitation instance method as follow:
invited_user = User.invite(:email => "new_user@example.com") invited_user.password = 'ad97nwj3o2' invited_user.accept_invitation
Since the invitations controller take care of all the invite/accept invitation process, in most cases you wouldn’t call the invite and accept_invitation methods directly. Instead, in your views, put a link to new_user_invitation_path or new_invitation_path(:user) or even /users/invitation/new to prepare and send an invitation. This email includes a link to accept the invitation like /users/invitation/accept?invitation_token=abcd123.
Note that if the invitation_token is not present or not valid, the visitor is redirected to after_sign_out_path_for(resource_name). You can also overwrite after_update_path_for and after_sign_out_path_for to customize your redirect hooks. More on Devise’s README, “Controller filters and helpers” section.
InvitationsController adds authenticate_inviter! filter to restrict who can send invitations. You can override this method to suit your needs.
Default behavior requires authentication of the same resource. For example, if your model User is :invitable, it will allow all authenticated users to send invitations to other users.
In a more probable scenario you would have a User model which is configured as invitable and an Admin model which is not. You would like to allow only admins to send invitations. To do so, simply overwrite the authenticate_inviter! method as follow:
module DeviseInvitable::Controllers::Helpers protected def authenticate_inviter! authenticate_admin! end end
DeviseInvitable uses flash messages with I18n with the flash keys :send_instructions, :invitation_token_invalid and :updated. To customize your app, you can modify the generated locale file:
en:
devise:
invitations:
send_instructions: 'An email with instructions about how to set the password has been sent.'
invitation_token_invalid: 'The invitation token provided is not valid!'
updated: 'Your password was set successfully. You are now signed in.'
You can also create distinct messages based on the resource you’ve configured using the singular name given in routes:
en:
devise:
invitations:
user:
send_instructions: 'A new user invitation has been sent.'
invitation_token_invalid: 'The invitation token provided is not valid!'
updated: 'Welcome on board! You are now signed in.'
The DeviseInvitable mailer uses the Devise pattern to create subject messages:
en:
devise:
mailer:
invitation_instructions:
subject: 'You got an invitation!'
user_subject: 'You got an user invitation!'
Take a look at the generated locale file (in config/locales/devise_invitable.en.yml) to check all available messages.
DeviseInvitable supports ActiveRecord and Mongoid, like Devise.
-
Fork the project.
-
Make your feature addition or bug fix.
-
Add specs for it. This is important so I don’t break it in a future version unintentionally.
-
Commit, do not mess with Rakefile, version, or changelog. (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.
-
Rémy Coutable (github.com/rymai)
Based on Sergio Cambra’s gem: github.com/scambra/devise_invitable
Check them all at: github.com/rymai/devise_invitable/contributors
Copyright © 2010 Sergio Cambra, Rémy Coutable. See LICENSE for details.