= DeviseInvitable
{<img src="https://travis-ci.org/scambra/devise_invitable.png"/>}[http://travis-ci.org/scambra/devise_invitable]

It adds support to devise[http://github.com/plataformatec/devise] for sending invitations by email (it requires to be authenticated) and accept the invitation setting the password.

DeviseInvitable currently supports Rails 3 and 4, if you want to use it with Rails 2.3 you must install version {0.2.3}[http://rubygems.org/gems/devise_invitable/versions/0.2.3]

If you want to use devise 3.0.x, you must use 1.2.1, newer versions require devise >= 3.1.0

== Installation

Install DeviseInvitable gem, it will also install dependencies (such as devise and warden):

  gem install devise_invitable

Add DeviseInvitable to your Gemfile (and Devise if you weren't using them):

  gem 'devise',           '>= 2.0.0'
  gem 'devise_invitable', '~> 1.1.0'

=== Automatic installation

Run the following generator to add DeviseInvitable’s configuration option in the Devise configuration file (config/initializers/devise.rb):

  rails generate devise_invitable:install

When you are done, you are ready to add DeviseInvitable to any of your Devise models using the following 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.

=== Manual installation

Follow the walkthrough for Devise and after it's done, follow this walkthrough.

== Devise Configuration
Add :invitable to the <tt>devise</tt> call 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

== ActiveRecord Migration
Add t.invitable to your Devise model migration:

  create_table :users do
    ...
      ## Invitable
      t.string   :invitation_token
      t.datetime :invitation_created_at
      t.datetime :invitation_sent_at
      t.datetime :invitation_accepted_at
      t.integer  :invitation_limit
      t.integer  :invited_by_id
      t.string   :invited_by_type
    ...
  end
  add_index :users, :invitation_token, :unique => true

or for a model that already exists, define a migration to add DeviseInvitable to your model:

  def change
      add_column :users, :invitation_token, :string
      add_column :users, :invitation_created_at, :datetime
      add_column :users, :invitation_sent_at, :datetime
      add_column :users, :invitation_accepted_at, :datetime
      add_column :users, :invitation_limit, :integer
      add_column :users, :invited_by_id, :integer
      add_column :users, :invited_by_type, :string
      add_index :users, :invitation_token, :unique => true
  end

  # Allow null encrypted_password
  change_column :users, :encrypted_password, :string, :null => true
  # Allow null password_salt (add it if you are using Devise's encryptable module)
  change_column :users, :password_salt, :string, :null => true

If you previously used devise_invitable with a :limit on :invitation_token, remove it:

  def up
    change_column :users, :invitation_token, :string, :limit => nil
  end

  def down
    change_column :users, :invitation_token, :string, :limit => 60
  end

== Mongoid Field Definitions
If you are using Mongoid, define the following fields and indexes within your invitable model:

  field :invitation_token, type: String
  field :invitation_created_at, type: Time
  field :invitation_sent_at, type: Time
  field :invitation_accepted_at, type: Time
  field :invitation_limit, type: Integer

  index( {invitation_token: 1}, {:background => true} )
  index( {invitation_by_id: 1}, {:background => true} )

You do not need to define a belongs_to relationship, as DeviseInvitable does this on your behalf:
  belongs_to :invited_by, :polymorphic => true

Remember to create indexes within the MongoDB database after deploying your changes.
  rake db:mongoid:create_indexes

== Model configuration

DeviseInvitable adds some new configuration options:

* invite_for: The period the generated invitation token is valid, after this period, the invited resource won't be able to accept the invitation. When invite_for is 0 (the default), the invitation won't expire.

You can set this configuration option in the Devise initializer as follow:

  # ==> Configuration for :invitable
  # The period the generated invitation token is valid, after
  # this period, the invited resource won't be able to accept the invitation.
  # When invite_for is 0 (the default), the invitation won't expire.
  # config.invite_for = 2.weeks

or directly as parameters to the <tt>devise</tt> method:

  devise :database_authenticatable, :confirmable, :invitable, :invite_for => 2.weeks

* invitation_limit: The number of invitations users can send.  The default value of nil means users can send as many invites as they want, there is no limit for any user, invitation_limit column is not used.  A setting of 0 means they can't send invitations.  A setting n > 0 means they can send n invitations. You can change invitation_limit column for some users so they can send more or less invitations, even with global invitation_limit = 0.

* invite_key: The key to be used to check existing users when sending an invitation. You can use multiple keys. This value must be a hash with the invite key as hash keys, and values that respond to the === operator(includes procs and regexes). The default value is looking for users by email and validating with Devise.email_regexp {:email => Devise.email_regexp}.

* validate_on_invite: force a record to be valid before being actually invited.

* resend_invitation: resend invitation if user with invited status is invited again. Enabled by default.

* invited_by_class_name: The class name of the inviting model. If this is nil, polymorphic association is used.

For more details, see <tt>config/initializers/devise.rb</tt> (after you invoked the "devise_invitable:install" generator described above).

== Configuring views

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

Then turn scoped views on in config/initializers/devise.rb:

  config.scoped_views = true

Please refer to {Devise's README}[http://github.com/plataformatec/devise] for more information about views.

== Configuring controllers

To change the controller's behavior, create a controller that inherits from <tt>Devise::InvitationsController</tt>. The available methods are: new, create, edit, and update. You should read the {original controllers source}[https://raw.github.com/scambra/devise_invitable/master/app/controllers/devise/invitations_controller.rb] before editing any of these actions. Your controller might now look something like this:

   class Users::InvitationsController < Devise::InvitationsController
     def update
       if this
         redirect_to root_path
       else
         super
       end
     end
   end

Now just tell Devise that you want to use your controller, the controller above is 'users/invitations', so our routes.rb would have this line:

  devise_for :users, :controllers => { :invitations => 'users/invitations' }

be sure that you generate the views and put them into the controller that you generated, so for this example it would be:

  rails generate devise_invitable:views users/invitations

To change behaviour of inviting or accepting users, you can simply override two methods:

  class Users::InvitationsController < Devise::InvitationsController
    private

    # this is called when creating invitation
    # should return an instance of resource class
    def invite_resource
      ## skip sending emails on invite
      resource_class.invite!(invite_params, current_inviter) do |u|
        u.skip_invitation = true
      end
    end

    # this is called when accepting invitation
    # should return an instance of resource class
    def accept_resource
      resource = resource_class.accept_invitation!(update_resource_params)
      ## Report accepting invitation to analytics
      Analytics.report('invite.accept', resource.id)
      resource
    end
  end

== Strong Parameters

When you customize your own views, you may end up adding new attributes to forms. Rails 4 moved the parameter sanitization from the model to the controller, causing DeviseInvitable to handle this concern at the controller as well. Read about it in {devise README}[http://github.com/plataformatec/devise#strong-parameters]

There are just two actions in DeviseInvitable that allows any set of parameters to be passed down to the model, therefore requiring sanitization. Their names and the permited parameters by default are:

* invite (Devise::InvitationsController#create) - Permits only the authentication keys (like email)
* accept_invitation (Devise::InvitationsController#update) - Permits invitation_token plus password and password_confirmation

Here is an example of what your application controller might need to include in order to add these parameters to the invitation view:

  before_filter :configure_permitted_parameters, if: :devise_controller?

  protected

  def configure_permitted_parameters
    # Only add some parameters
    devise_parameter_sanitizer.for(:accept_invitation).concat [:first_name, :last_name, :phone]
    # Override accepted parameters
    devise_parameter_sanitizer.for(:accept_invitation) do |u|
      u.permit(:first_name, :last_name, :phone, :password, :password_confirmation,
               :invitation_token)
    end
  end


== Usage

=== Send an invitation

To send an invitation to a user, use the <tt>invite!</tt> class method. <tt>:email</tt> must be present in the parameters hash. You can also include other attributes in the hash. The record will not be validated.

  User.invite!(:email => "new_user@example.com", :name => "John Doe")
  # => an invitation email will be sent to new_user@example.com

If you want to create the invitation but not send it, you can set <tt>skip_invitation</tt> to true.

  User.invite!(:email => "new_user@example.com", :name => "John Doe") do |u|
    u.skip_invitation = true
  end
  # => the record will be created, but the invitation email will not be sent

When skip_invitation is used, you must also then set the invitation_sent_at field when the user is sent their
token. Failure to do so will yield "Invalid invitation token" errors when the user attempts to accept the invite.
You can set it like so:

  user.deliver_invitation

You can add :skip_invitation to attributes hash if skip_invitation is added to attr_accessible.

  User.invite!(:email => "new_user@example.com", :name => "John Doe", :skip_invitation => true)
  # => the record will be created, but the invitation email will not be sent

Skip_invitation skips sending the email, but sets invitation_token, so invited_to_sign_up? on the
resulting user returns true.

You can send an invitation to an existing user if your workflow creates them separately:

  user = User.find(42)
  user.invite!(current_user)  # current user is optional to set the invited_by attribute

You can also set <tt>invited_by</tt> when using the <tt>invite!</tt> class method:

  User.invite!({:email => "new_user@example.com"}, current_user) # current_user will be set as invited_by

=== Accept an invitation

To accept an invitation with a token use the <tt>accept_invitation!</tt> class method. <tt>:invitation_token</tt> must be present in the parameters hash. You can also include other attributes in the hash.

  User.accept_invitation!(:invitation_token => params[:invitation_token], :password => "ad97nwj3o2", :name => "John Doe")

=== Callbacks

A callback event is fired before and after an invitation is accepted (User#accept_invitation!). For example, in your resource model you can add:

  after_invitation_accepted :email_invited_by

  def email_invited_by
     # ...
  end

The callbacks support all options and arguments available to the standard callbacks provided by AR.

=== Scopes

A pair of scopes to find those users that have accepted, and those that have not accepted, invitations are defined:

  User.invitation_accepted # => returns all Users for whom the invitation_accepted_at attribute is not nil
  User.invitation_not_accepted # => returns all Users for whom the invitation_accepted_at attribute is nil

== Integration in a Rails application

Since the invitations controller take care of all the creation/acceptation of an invitation, in most cases you wouldn't call the <tt>invite!</tt> and <tt>accept_invitation!</tt> methods directly.
Instead, in your views, put a link to <tt>new_user_invitation_path</tt> or <tt>new_invitation_path(:user)</tt> or even <tt>/users/invitation/new</tt> to prepare and send an invitation (to a user in this example).

After an invitation is created and sent, the inviter will be redirected to after_invite_path_for(resource_name), which is stored path or the same path as after_sign_in_path_for by default.

After an invitation is accepted, the invitee will be redirected to after_accept_path_for(resource), which is the same path as after_sign_in_path_for by default. If you want to override the path, override invitations controller and define after_accept_path_for method. This is useful in the common case that a user is invited to a specific location in your application. More on {Devise's README}[http://github.com/plataformatec/devise], "Controller filters and helpers" section.

The invitation email includes a link to accept the invitation that looks like this:  <tt>/users/invitation/accept?invitation_token=abcd123</tt>. When clicked, the invited must set a password in order to accept its invitation. Note that if the invitation_token is not present or not valid, the invited is redirected to after_sign_out_path_for(resource_name).

The controller sets the invited_by_id attribute for the new user to the current user.  This will let you easily keep track of who invited who.

== Controller filter

InvitationsController uses authenticate_inviter! filter to restrict who can send invitations. You can override this method in your ApplicationController.

Default behavior requires authentication of the same resource as the invited one. For example, if your model User is invitable, it will allow all authenticated users to send invitations to other users.

You would have a User model which is configured as invitable and an Admin model which is not. If you want to allow only admins to send invitations, simply overwrite the authenticate_inviter! method as follow:

  class ApplicationController < ActionController::Base
  protected
    def authenticate_inviter!
      authenticate_admin!(:force => true)
    end
  end

And include DeviseInvitable::Inviter module into Admin model:

  class Admin < ActiveRecord::Base
    devise :database_authenticatable, :validatable
    include DeviseInvitable::Inviter
  end

== Has many invitations

If you want to get all records invited by a resource, you should define has_many association in the model allowed to send invitations.

For the default behavior, define it like this:

  has_many :invitations, :class_name => self.to_s, :as => :invited_by

For the previous example, where admins send invitations to users, define it like this:

  has_many :invitations, :class_name => 'User', :as => :invited_by

== I18n

DeviseInvitable uses flash messages with I18n with the flash keys <tt>:send_instructions</tt>, <tt>:invitation_token_invalid</tt> and <tt>:updated</tt>. To customize your app, you can modify the generated locale file:

  en:
    devise:
      invitations:
        send_instructions: 'An invitation email has been sent to %{email}.'
        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 to %{email}.'
          invitation_token_invalid: 'Your invitation token is not valid!'
          updated: 'Welcome on board! You are now signed in.'

The DeviseInvitable mailer uses the same pattern as Devise to create mail subject messages:

  en:
    devise:
      mailer:
        invitation_instructions:
          subject: 'You got an invitation!'
          user_subject: 'You got a user invitation!'

Take a look at the generated locale file (in <tt>config/locales/devise_invitable.en.yml</tt>) to check all available messages.

== Other ORMs

DeviseInvitable supports ActiveRecord and Mongoid, like Devise.

== Testing

To test DeviseInvitable for the ActiveRecord ORM with RVM, Ruby 1.9.2, and Rubygems 1.8.17:

  rvm use 1.9.2
  rvm gemset create devise_invitable
  rvm gemset use devise_invitable
  gem install bundler
  bundle
  rake test DEVISE_ORM=active_record

== Contributors

Check them all at:

http://github.com/scambra/devise_invitable/contributors

Special thanks to rymai[http://github.com/rymai] for the Rails 3 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.

== Copyright

Copyright (c) 2014 Sergio Cambra. See LICENSE for details.