devise_invitable 0.3.6 → 0.4.0

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.1
 
-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.1.3'
+  gem 'devise_invitable', '~> 0.3.4'
 
 === 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,42 @@ 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.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 three 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.
+
+For more details, see <tt>config/initializers/devise.rb</tt> (after you invoked the "devise_invitable:install" generator described above).
 
 == Configuring views
 
@@ -96,31 +99,47 @@ Please refer to {Devise's README}[http://github.com/plataformatec/devise] for mo
 
 === 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")
 
 == 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_sign_in_path_for(resource_name).
+
+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).
+You can also overwrite after_sign_in_path_for and after_sign_out_path_for to customize your redirect hooks. More on {Devise's README}[http://github.com/plataformatec/devise], "Controller filters and helpers" section.
+
+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
@@ -131,12 +150,13 @@ You would have a User model which is configured as invitable and an Admin model
 
 == 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 +165,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 +190,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,11 +14,11 @@ 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
+      redirect_to after_sign_in_path_for(resource_name)
     else
       render_with_scope :new
     end
@@ -25,9 +26,12 @@ class Devise::InvitationsController < ApplicationController
 
   # 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.first(:conditions => { :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
@@ -41,4 +45,17 @@ class Devise::InvitationsController < ApplicationController
       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 
+      render_with_scope :new
+    end
+  end
 end

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:
-      invitation:
-        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}!", true)
   end
 end
 ActionController::Base.send :include, DeviseInvitable::Controllers::Helpers

data/lib/devise_invitable/mailer.rb

@@ -1,8 +1,14 @@
 module DeviseInvitable
   module Mailer
-    # Deliver an invitation when is requested
+    
+    # Deliver an invitation email
+    def invitation_instructions(record)
+      setup_mail(record, :invitation_instructions)
+    end
+    
     def invitation(record)
-      setup_mail(record, :invitation)
+      ActiveSupport::Deprecation.warn('invitation has been renamed to invitation_instructions')
+      invitation_instructions(record)
     end
   end
 end

data/lib/devise_invitable/model.rb

@@ -1,25 +1,32 @@
 module Devise
   module Models
-    # Invitable is responsible to send emails with invitations.
-    # When an invitation is sent to an email, an account is created for it.
-    # An invitation has a link to set the password, as reset password from recoverable.
+    # Invitable is responsible for sending invitation emails.
+    # When an invitation is sent to an email address, an account is created for it.
+    # Invitation email contains a link allowing the user to accept the invitation
+    # by setting a password (as reset password from Devise's recoverable module).
     #
     # Configuration:
     #
-    #   invite_for: the time you want the user will have to confirm the account after
-    #               is invited. When invite_for is zero, the invitation won't expire.
-    #               By default invite_for is 0.
+    #   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.
     #
     # Examples:
     #
-    #   User.find(1).invited?             # true/false
-    #   User.invite!(:email => 'someone@example.com') # send invitation
-    #   User.accept_invitation!(:invitation_token => '...')   # accept invitation with a token
-    #   User.find(1).accept_invitation!   # accept invitation
-    #   User.find(1).invite!   # reset invitation status and send invitation again
+    #   User.find(1).invited?                               # => true/false
+    #   User.invite!(:email => 'someone@example.com')       # => send invitation
+    #   User.accept_invitation!(:invitation_token => '...') # => accept invitation with a token
+    #   User.find(1).accept_invitation!                     # => accept invitation
+    #   User.find(1).invite!                                # => reset invitation status and send invitation again
     module Invitable
       extend ActiveSupport::Concern
 
+      attr_accessor :skip_invitation
+
+      included do
+        belongs_to :invited_by, :polymorphic => true
+      end
+
       # Accept an invitation by clearing invitation token and confirming it if model
       # is confirmable
       def accept_invitation!
@@ -34,26 +41,33 @@ module Devise
         persisted? && invitation_token.present?
       end
 
-      # Send invitation by email
-      def send_invitation
-        ::Devise.mailer.invitation(self).deliver
+      # 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
 
       # Reset invitation token and send invitation again
       def invite!
         if new_record? || invited?
-          self.skip_confirmation! if self.new_record? and self.respond_to? :skip_confirmation!
-          generate_invitation_token
-          save(:validate=>false)
-          send_invitation
+          @skip_password = true
+          self.skip_confirmation! if self.new_record? && self.respond_to?(:skip_confirmation!)
+          generate_invitation_token if self.invitation_token.nil?
+          self.invitation_sent_at = Time.now.utc
+          if save(:validate => self.class.validate_on_invite)
+            self.invited_by.decrement_invitation_limit! if self.invited_by
+            !!deliver_invitation unless @skip_invitation
+          end
         end
       end
 
-      def resend_invitation!
-        ActiveSupport::Deprecation.warn('resend_invitation! has been renamed to invite!')
-        self.invite!
-      end
-
       # Verify whether a invitation is active or not. If the user has been
       # invited, we need to calculate if the invitation time has not expired
       # for this user, in other words, if the invitation is still valid.
@@ -67,6 +81,28 @@ module Devise
       end
 
       protected
+        def decrement_invitation_limit!
+          if self.class.invitation_limit.present?
+            self.invitation_limit ||= self.class.invitation_limit
+            self.decrement!(:invitation_limit)
+          end
+        end
+
+        # Overriding the method in Devise's :validatable module so password is not required on inviting
+        def password_required?
+          !@skip_password && super
+        end
+
+        # Deliver the invitation email
+        def deliver_invitation
+          ::Devise.mailer.invitation_instructions(self).deliver
+        end
+
+        # Clear invitation token when reset password token is cleared too
+        def clear_reset_password_token
+          self.invitation_token = nil if invited?
+          super
+        end
 
         # Checks if the invitation for the user is within the limit time.
         # We do this by calculating if the difference between today and the
@@ -94,8 +130,7 @@ module Devise
         # Generates a new random token for invitation, and stores the time
         # this token is being generated
         def generate_invitation_token
-          self.invitation_token = Devise.friendly_token
-          self.invitation_sent_at = Time.now.utc
+          self.invitation_token   = self.class.invitation_token
         end
 
       module ClassMethods
@@ -103,33 +138,32 @@ module Devise
         # user and send invitation to it. If user is found, returns the user with an
         # email already exists error.
         # Attributes must contain the user email, other attributes will be set in the record
-        def invite!(attributes={})
-          invitable = find_or_initialize_with_error_by(:email, attributes.delete(:email))
+        def invite!(attributes={}, invited_by=nil, &block)
+          invitable = find_or_initialize_with_error_by(invite_key, attributes.delete(invite_key))
           invitable.attributes = attributes
+          invitable.invited_by = invited_by
 
           if invitable.new_record?
-            invitable.errors.clear if invitable.email.match Devise.email_regexp
+            invitable.errors.clear if invitable.email.try(:match, Devise.email_regexp)
           else
-            invitable.errors.add(:email, :taken) unless invitable.invited?
+            invitable.errors.add(invite_key, :taken) unless invitable.invited?
           end
 
-          invitable.invite! if invitable.errors.empty?
+          if invitable.errors.empty?
+            yield invitable if block_given?
+            invitable.invite!
+          end
           invitable
         end
 
-        def send_invitation(attributes = {})
-          ActiveSupport::Deprecation.warn('send_invitation has been renamed to invite!')
-          self.invite!(attributes)
-        end
-
         # Attempt to find a user by it's invitation_token to set it's password.
         # If a user is found, reset it's password and automatically try saving
         # the record. If not user is found, returns a new user containing an
         # error in invitation_token attribute.
         # Attributes must contain invitation_token, password and confirmation
         def accept_invitation!(attributes={})
-          invitable = find_or_initialize_with_error_by(:invitation_token, attributes[:invitation_token])
-          invitable.errors.add(:invitation_token, :invalid) if attributes[:invitation_token] && !invitable.new_record? && !invitable.valid_invitation?
+          invitable = find_or_initialize_with_error_by(:invitation_token, attributes.delete(:invitation_token))
+          invitable.errors.add(:invitation_token, :invalid) if invitable.invitation_token && invitable.persisted? && !invitable.valid_invitation?
           if invitable.errors.empty?
             invitable.attributes = attributes
             invitable.accept_invitation!
@@ -137,7 +171,15 @@ module Devise
           invitable
         end
 
+        # Generate a token checking if one does not already exist in the database.
+        def invitation_token
+          generate_token(:invitation_token)
+        end
+
         Devise::Models.config(self, :invite_for)
+        Devise::Models.config(self, :validate_on_invite)
+        Devise::Models.config(self, :invitation_limit)
+        Devise::Models.config(self, :invite_key)
       end
     end
   end

data/lib/devise_invitable/rails.rb

@@ -2,7 +2,7 @@ module DeviseInvitable
   class Engine < ::Rails::Engine
     
     ActiveSupport.on_load(:action_controller) { include DeviseInvitable::Controllers::UrlHelpers }
-    ActiveSupport.on_load(:action_view) { include DeviseInvitable::Controllers::UrlHelpers }
+    ActiveSupport.on_load(:action_view)       { include DeviseInvitable::Controllers::UrlHelpers }
     
     config.after_initialize do
       require 'devise/mailer'

data/lib/devise_invitable/routes.rb

@@ -1,10 +1,13 @@
 module ActionDispatch::Routing
   class Mapper
-    protected
-      def devise_invitation(mapping, controllers)
-        resource :invitation, :only => [:new, :create, :update], :path => mapping.path_names[:invitation], :controller => controllers[:invitations] do
-          get :edit, :path => mapping.path_names[:accept], :as => :accept
-        end
+    
+  protected
+    def devise_invitation(mapping, controllers)
+      resource :invitation, :only => [:new, :create, :update],
+        :path => mapping.path_names[:invitation], :controller => controllers[:invitations] do
+        get :edit, :path => mapping.path_names[:accept], :as => :accept
       end
+    end
+    
   end
 end

data/lib/devise_invitable/schema.rb

@@ -1,9 +1,34 @@
 module DeviseInvitable
   module Schema
-    # Creates invitation_token and invitation_sent_at.
+    # Add invitation_token and invitation_sent_at columns in the resource's database table.
+    #
+    # Examples
+    #
+    #   # For a new resource migration:
+    #   create_table :the_resources do
+    #     t.database_authenticatable :null => false # you need at least this
+    #     t.invitable
+    #     ...
+    #   end
+    #   add_index :the_resources, :invitation_token # for invitable
+    #
+    #   # or if the resource's table already exists, define a migration and put this in:
+    #   change_table :the_resources do |t|
+    #     t.string   :invitation_token, :limit => 60
+    #     t.datetime :invitation_sent_at
+    #     t.index    :invitation_token # for invitable
+    #   end
+    #
+    #   # And allow encrypted_password to be null:
+    #   change_column :the_resources, :encrypted_password, :string, :null => true
+    #   # the following line is only if you use Devise's encryptable module!
+    #   change_column :the_resources, :password_salt,      :string, :null => true
     def invitable
-      apply_devise_schema :invitation_token,   String, :limit => 20
+      apply_devise_schema :invitation_token,   String, :limit => 60
       apply_devise_schema :invitation_sent_at, DateTime
+      apply_devise_schema :invitation_limit, Integer
+      apply_devise_schema :invited_by_id, Integer
+      apply_devise_schema :invited_by_type, String
     end
   end
 end

data/lib/devise_invitable/version.rb

@@ -1,3 +1,3 @@
 module DeviseInvitable
-  VERSION = '0.3.6'
+  VERSION = '0.4.0'
 end

data/lib/devise_invitable.rb

@@ -1,16 +1,45 @@
 require 'devise'
 
-module Devise
-  # Time interval where the invitation token is valid.
-  mattr_accessor :invite_for
-  @@invite_for = 0
-end
-
-Devise.add_module :invitable, :controller => :invitations, :model => 'devise_invitable/model', :route => :invitation
-
 require 'devise_invitable/mailer'
 require 'devise_invitable/routes'
 require 'devise_invitable/schema'
 require 'devise_invitable/controllers/url_helpers'
 require 'devise_invitable/controllers/helpers'
 require 'devise_invitable/rails'
+
+module Devise
+  # Public: Validity period of the invitation token (default: 0). If 
+  # invite_for is 0 or nil, the invitation will never expire.
+  # Set invite_for in the Devise configuration file (in config/initializers/devise.rb).
+  #
+  #   config.invite_for = 2.weeks # => The invitation token will be valid 2 weeks
+  mattr_accessor :invite_for
+  @@invite_for = 0
+
+  # Public: Flag that force a record to be valid before being actually invited 
+  # (default: false).
+  #
+  # Examples (in config/initializers/devise.rb)
+  #
+  #   config.validate_on_invite = true
+  mattr_accessor :validate_on_invite
+  @@validate_on_invite = false
+
+  # Public: number of invitations the user is allowed to send
+  #
+  # Examples (in config/initializers/devise.rb)
+  #
+  #   config.invitation_limit = nil
+  mattr_accessor :invitation_limit
+  @@invitation_limit = nil
+  
+  # Public: The key to be used to check existing users when sending an invitation
+  #
+  # Examples (in config/initializers/devise.rb)
+  #
+  #   config.invite_key = :email
+  mattr_accessor :invite_key
+  @@invite_key = :email
+end
+
+Devise.add_module :invitable, :controller => :invitations, :model => 'devise_invitable/model', :route => :invitation

data/lib/generators/active_record/templates/migration.rb

@@ -1,18 +1,25 @@
 class DeviseInvitableAddTo<%= table_name.camelize %> < ActiveRecord::Migration
   def self.up
     change_table :<%= table_name %> do |t|
-      t.string   :invitation_token, :limit => 20
-      t.datetime :invitation_sent_at
-      t.index    :invitation_token # for invitable
+      t.string     :invitation_token, :limit => 60
+      t.datetime   :invitation_sent_at
+      t.integer    :invitation_limit
+      t.references :invited_by, :polymorphic => true
+      t.index      :invitation_token # for invitable
+      t.index      :invited_by_id
     end
     
     # And allow null encrypted_password and password_salt:
-    change_column :<%= table_name %>, :encrypted_password, :string, :null => true
-    change_column :<%= table_name %>, :password_salt,      :string, :null => true
+    change_column_null :<%= table_name %>, :encrypted_password, true
+<% if class_name.constantize.columns_hash['password_salt'] -%>
+    change_column_null :<%= table_name %>, :password_salt,      true
+<% end -%>
   end
   
   def self.down
-    remove_column :<%= table_name %>, :invitation_sent_at
-    remove_column :<%= table_name %>, :invitation_token
+    change_table :<%= table_name %> do |t|
+      remove_references :invited_by, :polymorphic => true
+      remove :invitation_limit, :invitation_sent_at, :invitation_token
+    end
   end
 end

data/lib/generators/devise_invitable/devise_invitable_generator.rb

@@ -5,6 +5,10 @@ module DeviseInvitable
 
       desc "Add :invitable directive in the given model. Also generate migration for ActiveRecord"
 
+      # def devise_generate_model
+      #   invoke "devise", [name]
+      # end
+
       def inject_devise_invitable_content
         path = File.join("app", "models", "#{file_path}.rb")
         inject_into_file(path, "invitable, :", :after => "devise :") if File.exists?(path)

data/lib/generators/devise_invitable/install_generator.rb

@@ -4,6 +4,10 @@ module DeviseInvitable
       source_root File.expand_path("../../templates", __FILE__)
       desc "Add DeviseInvitable config variables to the Devise initializer and copy DeviseInvitable locale files to your application."
       
+      # def devise_install
+      #   invoke "devise:install"
+      # end
+      
       def add_config_options_to_initializer
         devise_initializer_path = "config/initializers/devise.rb"
         if File.exist?(devise_initializer_path)
@@ -15,10 +19,21 @@ module DeviseInvitable
             inject_into_file(devise_initializer_path, :before => "  # ==> Configuration for :confirmable\n") do
 <<-CONTENT
   # ==> Configuration for :invitable
-  # Time interval where the invitation token is valid (default: 0).
-  # If invite_for is 0 or nil, the invitation will never expire.
+  # 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
   
+  # Number of invitations users can send.
+  # If invitation_limit is nil, users can send unlimited invitations.
+  # If invitation_limit is 0, users can't send invitations.
+  # If invitation_limit n > 0, users can send n invitations.
+  # Default: nil
+  # config.invitation_limit = 5
+  
+  # The key to be used to check existing users when sending an invitation
+  # config.invite_key = :email
+  
 CONTENT
             end
           end

data/lib/generators/mongoid/devise_invitable_generator.rb

@@ -0,0 +1,8 @@
+require 'generators/devise/orm_helpers'
+
+module Mongoid
+  module Generators
+    class DeviseInvitableGenerator < Rails::Generators::NamedBase
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: devise_invitable
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 15
   prerelease: 
   segments: 
   - 0
-  - 3
-  - 6
-  version: 0.3.6
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Sergio Cambra
@@ -15,45 +15,29 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-21 00:00:00 +01:00
+date: 2011-03-31 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: mocha
+  name: bundler
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
-        hash: 43
+        hash: 25
         segments: 
+        - 1
         - 0
-        - 9
-        - 8
-        version: 0.9.8
+        - 7
+        version: 1.0.7
   type: :development
   version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: capybara
-  prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 1
-        segments: 
-        - 0
-        - 3
-        - 9
-        version: 0.3.9
-  type: :development
-  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: rails
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -64,38 +48,24 @@ dependencies:
         - 0
         - 0
         version: 3.0.0
-  type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: sqlite3-ruby
-  prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  type: :development
-  version_requirements: *id004
+  type: :runtime
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: devise
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 19
+        hash: 31
         segments: 
         - 1
-        - 1
+        - 2
         - 0
-        version: 1.1.0
+        version: 1.2.0
   type: :runtime
-  version_requirements: *id005
+  version_requirements: *id003
 description: It adds support for send invitations by email (it requires to be authenticated) and accept the invitation by setting a password.
 email: 
 - sergio@entrecables.com
@@ -106,27 +76,26 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- app/controllers/devise/invitations_controller.rb
 - app/views/devise/invitations/edit.html.erb
 - app/views/devise/invitations/new.html.erb
-- app/views/devise/mailer/invitation.html.erb
-- app/controllers/devise/invitations_controller.rb~
-- app/controllers/devise/invitations_controller.rb
+- app/views/devise/mailer/invitation_instructions.html.erb
 - config/locales/en.yml
-- lib/devise_invitable/rails.rb
-- lib/devise_invitable/schema.rb
+- lib/devise_invitable.rb
 - lib/devise_invitable/mailer.rb
-- lib/devise_invitable/routes.rb
-- lib/devise_invitable/version.rb
 - lib/devise_invitable/model.rb
-- lib/devise_invitable/model.rb~
+- lib/devise_invitable/rails.rb
+- lib/devise_invitable/routes.rb
+- lib/devise_invitable/schema.rb
 - lib/devise_invitable/controllers/helpers.rb
 - lib/devise_invitable/controllers/url_helpers.rb
-- lib/devise_invitable.rb
+- lib/devise_invitable/version.rb
+- lib/generators/active_record/devise_invitable_generator.rb
+- lib/generators/active_record/templates/migration.rb
 - lib/generators/devise_invitable/views_generator.rb
 - lib/generators/devise_invitable/devise_invitable_generator.rb
 - lib/generators/devise_invitable/install_generator.rb
-- lib/generators/active_record/devise_invitable_generator.rb
-- lib/generators/active_record/templates/migration.rb
+- lib/generators/mongoid/devise_invitable_generator.rb
 - LICENSE
 - README.rdoc
 has_rdoc: true

data/app/controllers/devise/invitations_controller.rb~

@@ -1,48 +0,0 @@
-class Devise::InvitationsController < ApplicationController
-  include Devise::Controllers::InternalHelpers
-
-  before_filter :authenticate_inviter!, :only => [:new, :create]
-  before_filter :require_no_authentication, :only => [:edit, :update]
-  helper_method :after_sign_in_path_for
-
-  # GET /resource/invitation/new
-  def new
-    build_resource
-    render_with_scope :new
-  end
-
-  # POST /resource/invitation
-  def create
-    self.resource = resource_class.invite!(params[resource_name])
-
-    if resource.errors.empty?
-      puts params.inspect
-      set_flash_message :notice, :send_instructions, :email => self.resource.email
-      redirect_to after_sign_in_path_for(resource_name)
-    else
-      render_with_scope :new
-    end
-  end
-
-  # GET /resource/invitation/accept?invitation_token=abcdef
-  def edit
-    if params[:invitation_token] && self.resource = resource_class.first(:conditions => { :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
-  def update
-    self.resource = resource_class.accept_invitation!(params[resource_name])
-
-    if resource.errors.empty?
-      set_flash_message :notice, :updated
-      sign_in_and_redirect(resource_name, resource)
-    else
-      render_with_scope :edit
-    end
-  end
-end

data/lib/devise_invitable/model.rb~

@@ -1,129 +0,0 @@
-module Devise
-  module Models
-    # Invitable is responsible to send emails with invitations.
-    # When an invitation is sent to an email, an account is created for it.
-    # An invitation has a link to set the password, as reset password from recoverable.
-    #
-    # Configuration:
-    #
-    #   invite_for: the time you want the user will have to confirm the account after
-    #               is invited. When invite_for is zero, the invitation won't expire.
-    #               By default invite_for is 0.
-    #
-    # Examples:
-    #
-    #   User.find(1).invited?             # true/false
-    #   User.invite!(:email => 'someone@example.com') # send invitation
-    #   User.accept_invitation!(:invitation_token => '...')   # accept invitation with a token
-    #   User.find(1).accept_invitation!   # accept invitation
-    #   User.find(1).invite!   # reset invitation status and send invitation again
-    module Invitable
-      extend ActiveSupport::Concern
-
-      # Accept an invitation by clearing invitation token and confirming it if model
-      # is confirmable
-      def accept_invitation!
-        if self.invited?
-          self.invitation_token = nil
-          self.save
-        end
-      end
-
-      # Verifies whether a user has been invited or not
-      def invited?
-        persisted? && invitation_token.present?
-      end
-
-      # Send invitation by email
-      def send_invitation
-        ::Devise.mailer.invitation(self).deliver
-      end
-
-      # Reset invitation token and send invitation again
-      def invite!
-        if new_record? || invited?
-          self.skip_confirmation! if self.new_record? and self.respond_to? :skip_confirmation!
-          generate_invitation_token
-          save(:validate=>false)
-          send_invitation
-        end
-      end
-
-      # Verify whether a invitation is active or not. If the user has been
-      # invited, we need to calculate if the invitation time has not expired
-      # for this user, in other words, if the invitation is still valid.
-      def valid_invitation?
-        invited? && invitation_period_valid?
-      end
-
-      protected
-
-        # Checks if the invitation for the user is within the limit time.
-        # We do this by calculating if the difference between today and the
-        # invitation sent date does not exceed the invite for time configured.
-        # Invite_for is a model configuration, must always be an integer value.
-        #
-        # Example:
-        #
-        #   # invite_for = 1.day and invitation_sent_at = today
-        #   invitation_period_valid?   # returns true
-        #
-        #   # invite_for = 5.days and invitation_sent_at = 4.days.ago
-        #   invitation_period_valid?   # returns true
-        #
-        #   # invite_for = 5.days and invitation_sent_at = 5.days.ago
-        #   invitation_period_valid?   # returns false
-        #
-        #   # invite_for = nil
-        #   invitation_period_valid?   # will always return true
-        #
-        def invitation_period_valid?
-          invitation_sent_at && (self.class.invite_for.to_i.zero? || invitation_sent_at.utc >= self.class.invite_for.ago)
-        end
-
-        # Generates a new random token for invitation, and stores the time
-        # this token is being generated
-        def generate_invitation_token
-          self.invitation_token = Devise.friendly_token
-          self.invitation_sent_at = Time.now.utc
-        end
-
-      module ClassMethods
-        # Attempt to find a user by it's email. If a record is not found, create a new
-        # user and send invitation to it. If user is found, returns the user with an
-        # email already exists error.
-        # Attributes must contain the user email, other attributes will be set in the record
-        def invite!(attributes={})
-          invitable = find_or_initialize_with_error_by(:email, attributes.delete(:email))
-          invitable.attributes = attributes
-
-          if invitable.new_record?
-            invitable.errors.clear if invitable.email.try(:match, Devise.email_regexp)
-          else
-            invitable.errors.add(:email, :taken) unless invitable.invited?
-          end
-
-          invitable.invite! if invitable.errors.empty?
-          invitable
-        end
-
-        # Attempt to find a user by it's invitation_token to set it's password.
-        # If a user is found, reset it's password and automatically try saving
-        # the record. If not user is found, returns a new user containing an
-        # error in invitation_token attribute.
-        # Attributes must contain invitation_token, password and confirmation
-        def accept_invitation!(attributes={})
-          invitable = find_or_initialize_with_error_by(:invitation_token, attributes.delete(:invitation_token))
-          invitable.errors.add(:invitation_token, :invalid) if attributes[:invitation_token] && !invitable.new_record? && !invitable.valid_invitation?
-          if invitable.errors.empty?
-            invitable.attributes = attributes
-            invitable.accept_invitation!
-          end
-          invitable
-        end
-
-        Devise::Models.config(self, :invite_for)
-      end
-    end
-  end
-end