devise_invitable 0.3.4 → 0.6.1

data/lib/devise_invitable/model.rb

@@ -1,31 +1,47 @@
 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
 
-      # Accept an invitation by clearing invitation token and confirming it if model
-      # is confirmable
+      attr_accessor :skip_invitation
+
+      included do
+        include ::DeviseInvitable::Inviter        
+        belongs_to :invited_by, :polymorphic => true
+        
+        include ActiveSupport::Callbacks
+        define_callbacks :invitation_accepted
+        
+        attr_writer :skip_password
+      end
+
+      # Accept an invitation by clearing invitation token and and setting invitation_accepted_at
+      # Confirms it if model is confirmable
       def accept_invitation!
-        if self.invited?
-          self.invitation_token = nil
-          self.save
+        if self.invited? && self.valid?
+          run_callbacks :invitation_accepted do
+            self.invitation_token = nil
+            self.invitation_accepted_at = Time.now.utc if respond_to? :"invitation_accepted_at="
+            self.save(:validate => false)
+          end
         end
       end
 
@@ -34,26 +50,18 @@ module Devise
         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
+        was_invited = invited?
+        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 => false)
+          self.invited_by.decrement_invitation_limit! if !was_invited and self.invited_by.present?
+          deliver_invitation unless @skip_invitation
         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.
@@ -61,7 +69,26 @@ module Devise
         invited? && invitation_period_valid?
       end
 
+      # Only verify password when is not invited
+      def valid_password?(password)
+        super unless invited?
+      end
+      
+      def reset_password!(new_password, new_password_confirmation)
+        super
+        accept_invitation!
+      end
+
       protected
+        # 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
 
         # Checks if the invitation for the user is within the limit time.
         # We do this by calculating if the difference between today and the
@@ -89,32 +116,50 @@ 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
         # 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.
+        # If user is found and still have pending invitation, email is resend unless
+        # resend_invitation is set to false
         # 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
+        def _invite(attributes={}, invited_by=nil, &block)
+          invitable = find_or_initialize_with_error_by(invite_key, attributes.delete(invite_key))
+          invitable.assign_attributes(attributes, :as => inviter_role(invited_by))
+          invitable.invited_by = invited_by
 
+          invitable.skip_password = true
+          invitable.valid? if self.validate_on_invite
           if invitable.new_record?
-            invitable.errors.clear if invitable.email.match Devise.email_regexp
+            invitable.errors.clear if !self.validate_on_invite and 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? && self.resend_invitation
+          end
+
+          if invitable.errors.empty?
+            yield invitable if block_given?
+            mail = invitable.invite!
           end
+          [invitable, mail]
+        end
+        
+        # Override this method if the invitable is using Mass Assignment Security
+        # and the inviter has a non-default role.
+        def inviter_role(inviter)
+          :default
+        end
 
-          invitable.invite! if invitable.errors.empty?
+        def invite!(attributes={}, invited_by=nil, &block)
+          invitable, mail = _invite(attributes, invited_by, &block)
           invitable
         end
 
-        def send_invitation(attributes = {})
-          ActiveSupport::Deprecation.warn('send_invitation has been renamed to invite!')
-          self.invite!(attributes)
+        def invite_mail!(attributes={}, invited_by=nil, &block)
+          invitable, mail = _invite(attributes, invited_by, &block)
+          mail
         end
 
         # Attempt to find a user by it's invitation_token to set it's password.
@@ -123,8 +168,8 @@ module Devise
         # 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!
@@ -132,8 +177,28 @@ 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
+        
+        # Callback convenience methods
+        def before_invitation_accepted(*args, &blk)
+          set_callback(:invitation_accepted, :before, *args, &blk)
+        end
+        
+        def after_invitation_accepted(*args, &blk)
+          set_callback(:invitation_accepted, :after, *args, &blk)
+        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)
+        Devise::Models.config(self, :resend_invitation)
       end
     end
   end
 end
+

data/lib/devise_invitable/model.rb~

@@ -0,0 +1,210 @@
+module Devise
+  module Models
+    # 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 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
+    module Invitable
+      extend ActiveSupport::Concern
+
+      attr_accessor :skip_invitation
+
+      included do
+        include ::DeviseInvitable::Inviter        
+        belongs_to :invited_by, :polymorphic => true
+        
+        include ActiveSupport::Callbacks
+        define_callbacks :invitation_accepted
+        
+        attr_writer :skip_password
+      end
+
+      # Accept an invitation by clearing invitation token and and setting invitation_accepted_at
+      # Confirms it if model is confirmable
+      def accept_invitation!
+        if self.invited? && self.valid?
+          run_callbacks :invitation_accepted do
+            self.invitation_token = nil
+            self.invitation_accepted_at = Time.now.utc if respond_to? :"invitation_accepted_at="
+            self.save(:validate => false)
+          end
+        end
+      end
+
+      # Verifies whether a user has been invited or not
+      def invited?
+        persisted? && invitation_token.present?
+      end
+
+      # Reset invitation token and send invitation again
+      def invite!
+        was_invited = invited?
+        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 => false)
+          self.invited_by.decrement_invitation_limit! if !was_invited and self.invited_by.present?
+          deliver_invitation unless @skip_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
+
+      # Only verify password when is not invited
+      def valid_password?(password)
+        super unless invited?
+      end
+=begin      
+      def reset_password!(new_password, new_password_confirmation)
+        super
+        accept_invitation!
+      end
+=end
+      protected
+        # 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
+        # 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   = self.class.invitation_token
+        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.
+        # If user is found and still have pending invitation, email is resend unless
+        # resend_invitation is set to false
+        # Attributes must contain the user email, other attributes will be set in the record
+        def _invite(attributes={}, invited_by=nil, &block)
+          invitable = find_or_initialize_with_error_by(invite_key, attributes.delete(invite_key))
+          invitable.assign_attributes(attributes, :as => inviter_role(invited_by))
+          invitable.invited_by = invited_by
+
+          invitable.skip_password = true
+          invitable.valid? if self.validate_on_invite
+          if invitable.new_record?
+            invitable.errors.clear if !self.validate_on_invite and invitable.email.try(:match, Devise.email_regexp)
+          else
+            invitable.errors.add(invite_key, :taken) unless invitable.invited? && self.resend_invitation
+          end
+
+          if invitable.errors.empty?
+            yield invitable if block_given?
+            mail = invitable.invite!
+          end
+          [invitable, mail]
+        end
+        
+        # Override this method if the invitable is using Mass Assignment Security
+        # and the inviter has a non-default role.
+        def inviter_role(inviter)
+          :default
+        end
+
+        def invite!(attributes={}, invited_by=nil, &block)
+          invitable, mail = _invite(attributes, invited_by, &block)
+          invitable
+        end
+
+        def invite_mail!(attributes={}, invited_by=nil, &block)
+          invitable, mail = _invite(attributes, invited_by, &block)
+          mail
+        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 invitable.invitation_token && invitable.persisted? && !invitable.valid_invitation?
+          if invitable.errors.empty?
+            invitable.attributes = attributes
+            invitable.accept_invitation!
+          end
+          invitable
+        end
+
+        # Generate a token checking if one does not already exist in the database.
+        def invitation_token
+          generate_token(:invitation_token)
+        end
+        
+        # Callback convenience methods
+        def before_invitation_accepted(*args, &blk)
+          set_callback(:invitation_accepted, :before, *args, &blk)
+        end
+        
+        def after_invitation_accepted(*args, &blk)
+          set_callback(:invitation_accepted, :after, *args, &blk)
+        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)
+        Devise::Models.config(self, :resend_invitation)
+      end
+    end
+  end
+end
+

data/lib/devise_invitable/rails.rb

@@ -2,9 +2,12 @@ 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
+    # We use to_prepare instead of after_initialize here because Devise is a Rails engine; its
+    # mailer is reloaded like the rest of the user's app.  Got to make sure that our mailer methods
+    # are included each time Devise::Mailer is (re)loaded.
+    config.to_prepare do
       require 'devise/mailer'
       Devise::Mailer.send :include, DeviseInvitable::Mailer
     end

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,36 @@
 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.datetime :invitation_accepted_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_accepted_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

@@ -0,0 +1,3 @@
+module DeviseInvitable
+  VERSION = '0.6.1'
+end

data/lib/devise_invitable.rb

@@ -1,16 +1,58 @@
 require 'devise'
 
-module Devise
-  # Time interval where the invitation token is valid.
-  mattr_accessor :invite_for
-  @@invite_for = 0
+module DeviseInvitable
+  autoload :Inviter, 'devise_invitable/inviter'
 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
+
+  # Public: Resend invitation if user with invited status is invited again
+  # (default: true)
+  #
+  # Example (in config/initializers/devise.rb)
+  #
+  #   config.resend_invitation = false
+  mattr_accessor :resend_invitation
+  @@resend_invitation = true
+end
+
+Devise.add_module :invitable, :controller => :invitations, :model => 'devise_invitable/model', :route => :invitation

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

@@ -1,18 +1,26 @@
 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.datetime   :invitation_accepted_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|
+      t.remove_references :invited_by, :polymorphic => true
+      t.remove :invitation_limit, :invitation_sent_at, :invitation_accepted_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,25 @@ 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
+  
+  # Flag that force a record to be valid before being actually invited 
+  # Default: false
+  # config.validate_on_invite = true
+
 CONTENT
             end
           end