devise_invitable 0.3.4 → 0.6.1

data/README.rdoc

@@ -2,26 +2,26 @@
 
 It adds support to devise[http://github.com/plataformatec/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
+DeviseInvitable currently only support Rails 3, 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]
 
-== Installation for Rails ~> 3.0.0 and Devise ~> 1.1.2
+== Installation for Rails ~> 3.0 and Devise ~> 1.2
 
-Install devise_invitable gem, it should install dependencies (such as devise and warden):
+Install DeviseInvitable gem, it will also install dependencies (such as devise and warden):
 
-  sudo gem install devise_invitable
+  gem install devise_invitable
 
-Configure devise_invitable in your Gemfile (and devise if you weren't using them):
+Add DeviseInvitable to your Gemfile (and Devise if you weren't using them):
 
-  gem 'devise'
-  gem 'devise_invitable'
+  gem 'devise',           '~> 1.2.0'
+  gem 'devise_invitable', '~> 0.4.0'
 
 === Automatic installation
 
-After you install DeviseInvitable and add it to your Gemfile, you need to run the generator:
+Run the following generator to add DeviseInvitable’s configuration option in the Devise configuration file (config/initializers/devise.rb):
 
   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:
+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
 
@@ -31,7 +31,7 @@ Replace MODEL by the class name you want to add DeviseInvitable, like User, Admi
 
 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):
+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
@@ -46,39 +46,47 @@ Add t.invitable to your Devise model migration:
   end
   add_index :users, :invitation_token
 
-or for a model that is already created, define a migration to add DeviseInvitable to your model:
+or for a model that already exists, define a migration to add DeviseInvitable to your model:
 
   change_table :users do |t|
-    t.string   :invitation_token, :limit => 20
+    t.string   :invitation_token, :limit => 60
     t.datetime :invitation_sent_at
+    t.datetime :invitation_accepted_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.
+  # Allow null encrypted_password
+  change_column_null :users, :encrypted_password, true
+  # Allow null password_salt (add it if you are using Devise's encryptable module)
+  change_column_null :users, :password_salt, true
 
 == Model configuration
 
-DeviseInvitable adds a new configuration option:
+DeviseInvitable adds some new configuration options:
 
-  * invite_for         => The validity duration for an invitation. Default is 0, which means invitations doesn't expire.
+* 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 those configuration options in the Devise initializer as follow:
+You can set this configuration option 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
+  # 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 inside your Devise models:
+or directly as parameters to the <tt>devise</tt> method:
 
   devise :database_authenticatable, :confirmable, :invitable, :invite_for => 2.weeks
 
-For details, see <tt>config/initializer/devise.rb</tt> (after you invoked the "devise_invitable:install" generator described above).
+* invitation_limit: The number of invitations users can send.  The default value of nil means users can send as many invites as they want.  A setting of 0 means they can't send invitations.  A setting n > 0 means they can send n invitations.
+
+* invite_key: The key to be used to check existing users when sending an invitation. The key must be an unique field. The default value is looking for users by email.
+
+* 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.
+
+For more details, see <tt>config/initializers/devise.rb</tt> (after you invoked the "devise_invitable:install" generator described above).
 
 == Configuring views
 
@@ -92,51 +100,123 @@ You can also use the generator to generate scoped views:
 
 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
+
 == Usage
 
 === Send an invitation
 
-To send an invitation to a user, use the <tt>invite!</tt> class method. You must set <tt>email</tt> in the parameters hash:
-You can also include other attributes in the hash. The record will not be validated.
+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")
+  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
+
+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
+
 === Accept an invitation
 
-To accept an invitation with a token use the <tt>accept_invitation</tt> class method. You must set <tt>invitation_token</tt> in the parameters hash. You can include other attributes in the hash (as in the <tt>update_attributes</tt> method for example).
+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")
 
-  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.
 
 == Integration in a Rails application
 
-Since the invitations controller take care of all the invite/accept invitation process, 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.
-This email includes a link to accept the invitation like <tt>/users/invitation/accept?invitation_token=abcd123</tt>.
+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. For example, if your model User is <tt>:invitable</tt>, it will allow all authenticated users to send invitations to other users.
+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 would like to allow only admins to send invitations, simply overwrite the authenticate_inviter! method as follow:
+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!
+      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.class.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> and <tt>:updated</tt>. To customize your app, you can modify the generated locale file:
+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 email with instructions about how to set the password has been sent.'
+        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:
@@ -145,17 +225,18 @@ You can also create distinct messages based on the resource you've configured us
     devise:
       invitations:
         user:
-          send_instructions: 'A new user invitation has been sent.'
+          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 Devise pattern to create subject messages:
+The DeviseInvitable mailer uses the same pattern as Devise to create mail subject messages:
 
   en:
     devise:
       mailer:
-        invitation:
+        invitation_instructions:
           subject: 'You got an invitation!'
-          user_subject: 'You got an user 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.
 
@@ -169,7 +250,7 @@ Check them all at:
 
 http://github.com/scambra/devise_invitable/contributors
 
-Special thanks to rymai[http://github.com/rymai] for rails3 support, his fork was a great help.
+Special thanks to rymai[http://github.com/rymai] for the Rails 3 support, his fork was a great help.
 
 == Note on Patches/Pull Requests
  

data/app/controllers/devise/invitations_controller.rb

@@ -2,6 +2,7 @@ class Devise::InvitationsController < ApplicationController
   include Devise::Controllers::InternalHelpers
 
   before_filter :authenticate_inviter!, :only => [:new, :create]
+  before_filter :has_invitations_left?, :only => [:create]
   before_filter :require_no_authentication, :only => [:edit, :update]
   helper_method :after_sign_in_path_for
 
@@ -13,21 +14,24 @@ class Devise::InvitationsController < ApplicationController
 
   # POST /resource/invitation
   def create
-    self.resource = resource_class.invite!(params[resource_name])
+    self.resource = resource_class.invite!(params[resource_name], current_inviter)
 
     if resource.errors.empty?
-      set_flash_message :notice, :send_instructions
-      redirect_to after_update_path_for(resource_name)
+      set_flash_message :notice, :send_instructions, :email => self.resource.email
+      respond_with resource, :location => after_invite_path_for(resource)
     else
-      render_with_scope :new
+      respond_with_navigational(resource) { render_with_scope :new }
     end
   end
 
   # GET /resource/invitation/accept?invitation_token=abcdef
   def edit
-    self.resource = resource_class.new
-    resource.invitation_token = params[:invitation_token]
-    render_with_scope :edit
+    if params[:invitation_token] && self.resource = resource_class.to_adapter.find_first( :invitation_token => params[:invitation_token] )
+      render_with_scope :edit
+    else
+      set_flash_message(:alert, :invitation_token_invalid)
+      redirect_to after_sign_out_path_for(resource_name)
+    end
   end
 
   # PUT /resource/invitation
@@ -36,9 +40,32 @@ class Devise::InvitationsController < ApplicationController
 
     if resource.errors.empty?
       set_flash_message :notice, :updated
-      sign_in_and_redirect(resource_name, resource)
+      sign_in(resource_name, resource)
+      respond_with resource, :location => after_accept_path_for(resource)
     else
-      render_with_scope :edit
+      respond_with_navigational(resource){ render_with_scope :edit }
+    end
+  end
+
+  protected
+  def current_inviter
+    @current_inviter ||= authenticate_inviter!
+  end
+
+  def has_invitations_left?
+    unless current_inviter.nil? || current_inviter.has_invitations_left?
+      build_resource
+      set_flash_message :alert, :no_invitations_remaining
+      respond_with_navigational(resource) { render_with_scope :new }
     end
   end
+
+  def after_invite_path_for(resource)
+    after_sign_in_path_for(resource)
+  end
+
+  def after_accept_path_for(resource)
+    after_sign_in_path_for(resource)
+  end
 end
+

data/app/views/devise/invitations/new.html.erb

@@ -1,6 +1,6 @@
 <h2>Send invitation</h2>
 
-<%= form_for resource, :as => resource_name, :url => invitation_path(resource_name) do |f| %>
+<%= form_for resource, :as => resource_name, :url => invitation_path(resource_name), :html => {:method => :post} do |f| %>
   <%= devise_error_messages! %>
 
   <p><%= f.label :email %><br />

data/config/locales/en.yml

@@ -1,8 +1,10 @@
 en:
   devise:
     invitations:
-      send_instructions: 'An email with instructions about how to set the password has been sent.'
+      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.'
+      no_invitations_remaining: "No invitations remaining"
     mailer:
-      invitiation:
-        subject: 'Invitation'
+      invitation_instructions:
+        subject: 'Invitation instructions'

data/lib/devise_invitable/controllers/helpers.rb

@@ -1,12 +1,7 @@
 module DeviseInvitable::Controllers::Helpers
   protected
-  def authenticate_resource!
-    ActiveSupport::Deprecation.warn('authenticate_resource! has been renamed to authenticate_inviter!')
-    authenticate_inviter!
-  end
-
   def authenticate_inviter!
-    send(:"authenticate_#{resource_name}!")
+    send(:"authenticate_#{resource_name}!", :force => true)
   end
 end
 ActionController::Base.send :include, DeviseInvitable::Controllers::Helpers

data/lib/devise_invitable/inviter.rb

@@ -0,0 +1,39 @@
+module DeviseInvitable
+  module Inviter
+    extend ActiveSupport::Concern
+
+    included do
+      extend ClassMethods
+      attr_writer :invitation_limit unless respond_to? :invitation_limit
+    end
+
+    def invitation_limit
+      self[:invitation_limit] || self.class.invitation_limit
+    end
+
+    # Return true if this user has invitations left to send
+    def has_invitations_left?
+      if self.class.invitation_limit.present?
+        if invitation_limit
+          return invitation_limit > 0
+        else
+          return self.class.invitation_limit > 0
+        end
+      else
+        return true
+      end
+    end
+
+    protected
+      def decrement_invitation_limit!
+        if self.class.invitation_limit.present?
+          self.invitation_limit ||= self.class.invitation_limit
+          self.update_attribute(:invitation_limit, invitation_limit - 1)
+        end
+      end
+
+    module ClassMethods
+      Devise::Models.config(self, :invitation_limit)
+    end
+  end
+end

data/lib/devise_invitable/mailer.rb

@@ -1,8 +1,9 @@
 module DeviseInvitable
   module Mailer
-    # Deliver an invitation when is requested
-    def invitation(record)
-      setup_mail(record, :invitation)
+    
+    # Deliver an invitation email
+    def invitation_instructions(record)
+      devise_mail(record, :invitation_instructions)
     end
   end
 end