Module: Devise::Models::Invitable

Extended by:
ActiveSupport::Concern
Defined in:
lib/devise_invitable/models.rb

Overview

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_to_sign_up?                    # => true/false
User.invite!(email: '[email protected]')          # => 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

Defined Under Namespace

Modules: ClassMethods

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#completing_invite ⇒ Object

Returns the value of attribute completing_invite.



28
29
30
 
# File 'lib/devise_invitable/models.rb', line 28

def completing_invite
  @completing_invite
end

#raw_invitation_token ⇒ Object (readonly)

Returns the value of attribute raw_invitation_token.



29
30
31
 
# File 'lib/devise_invitable/models.rb', line 29

def raw_invitation_token
  @raw_invitation_token
end

#skip_invitation ⇒ Object

Returns the value of attribute skip_invitation.



27
28
29
 
# File 'lib/devise_invitable/models.rb', line 27

def skip_invitation
  @skip_invitation
end

Class Method Details

.required_fields(klass) ⇒ Object 



77
78
79
80
81
82
83
 
# File 'lib/devise_invitable/models.rb', line 77

def self.required_fields(klass)
  fields = [:invitation_token, :invitation_created_at, :invitation_sent_at, :invitation_accepted_at,
   :invitation_limit, Devise.invited_by_foreign_key || :invited_by_id, :invited_by_type]
  fields << :invitations_count if defined?(ActiveRecord) && self < ActiveRecord::Base
  fields -= [:invited_by_type] if Devise.invited_by_class_name
  fields
end

Instance Method Details

#accept_invitation ⇒ Object

Accept an invitation by clearing invitation token and and setting invitation_accepted_at



86
87
88
89
 
# File 'lib/devise_invitable/models.rb', line 86

def accept_invitation
  self.invitation_accepted_at = Time.now.utc
  self.invitation_token = nil
end

#accept_invitation! ⇒ Object

Accept an invitation by clearing invitation token and and setting invitation_accepted_at Saves the model and confirms it if model is confirmable, running invitation_accepted callbacks



93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/devise_invitable/models.rb', line 93

def accept_invitation!
  if self.invited_to_sign_up?
    @accepting_invitation = true
    run_callbacks :invitation_accepted do
      self.accept_invitation
      self.confirmed_at ||= self.invitation_accepted_at if self.respond_to?(:confirmed_at=)
      self.save
    end.tap do |saved|
      self.rollback_accepted_invitation if !saved
      @accepting_invitation = false
    end
  end
end

#accepted_or_not_invited? ⇒ Boolean

Verifies whether a user has accepted an invitation (false when user is accepting it), or was never invited

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/devise_invitable/models.rb', line 134

def accepted_or_not_invited?
  invitation_accepted? || !invited_to_sign_up?
end

#accepting_invitation? ⇒ Boolean

Returns true if accept_invitation! was called

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/devise_invitable/models.rb', line 124

def accepting_invitation?
  @accepting_invitation
end

#add_taken_error(key) ⇒ Object 



231
232
233
 
# File 'lib/devise_invitable/models.rb', line 231

def add_taken_error(key)
  errors.add(key, :taken)
end

#clear_errors_on_valid_keys ⇒ Object 



201
202
203
204
205
 
# File 'lib/devise_invitable/models.rb', line 201

def clear_errors_on_valid_keys
  self.class.invite_key.each do |key, value|
    self.errors.delete(key) if value === self.send(key)
  end
end

#clear_reset_password_token ⇒ Object 



195
196
197
198
199
 
# File 'lib/devise_invitable/models.rb', line 195

def clear_reset_password_token
  reset_password_token_present = reset_password_token.present?
  super
  accept_invitation! if reset_password_token_present && valid_invitation?
end

#confirmation_required_for_invited? ⇒ Boolean

Returns:

  • (Boolean) 


219
220
221
 
# File 'lib/devise_invitable/models.rb', line 219

def confirmation_required_for_invited?
  respond_to?(:confirmation_required?, true) && confirmation_required?
end

#created_by_invite? ⇒ Boolean

Verify wheather a user is created by invitation, irrespective to invitation status

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/devise_invitable/models.rb', line 114

def created_by_invite?
  invitation_created_at.present?
end

#deliver_invitation(options = {}) ⇒ Object

Deliver the invitation email



208
209
210
211
212
 
# File 'lib/devise_invitable/models.rb', line 208

def deliver_invitation(options = {})
  generate_invitation_token! unless @raw_invitation_token
  self.update_attribute :invitation_sent_at, Time.now.utc unless self.invitation_sent_at
  send_devise_notification(:invitation_instructions, @raw_invitation_token, options)
end

#encrypted_invitation_token ⇒ Object

provide alias to the encrypted invitation_token stored by devise



215
216
217
 
# File 'lib/devise_invitable/models.rb', line 215

def encrypted_invitation_token
  self.invitation_token
end

#invitation_accepted? ⇒ Boolean

Verifies whether a user accepted an invitation (false when user is accepting it)

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/devise_invitable/models.rb', line 129

def invitation_accepted?
  !accepting_invitation? && invitation_accepted_at.present?
end

#invitation_due_at ⇒ Object 



223
224
225
226
227
228
229
 
# File 'lib/devise_invitable/models.rb', line 223

def invitation_due_at
  return nil if (self.class.invite_for == 0 || self.class.invite_for.nil?)
  #return nil unless self.class.invite_for

  time = self.invitation_created_at || self.invitation_sent_at
  time + self.class.invite_for
end

#invitation_taken? ⇒ Boolean

Returns:

  • (Boolean) 


235
236
237
 
# File 'lib/devise_invitable/models.rb', line 235

def invitation_taken?
  !invited_to_sign_up?
end

#invite!(invited_by = nil, options = {}) {|_self| ... } ⇒ Object

Reset invitation token and send invitation again

Yields:

  • (_self)

Yield Parameters:



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/devise_invitable/models.rb', line 139

def invite!(invited_by = nil, options = {})
  # This is an order-dependant assignment, this can't be moved
  was_invited = invited_to_sign_up?

  # Required to workaround confirmable model's confirmation_required? method
  # being implemented to check for non-nil value of confirmed_at
  if new_record_and_responds_to?(:confirmation_required?)
    def self.confirmation_required?; false; end
  end

  yield self if block_given?
  generate_invitation_token if no_token_present_or_skip_invitation?

  run_callbacks :invitation_created do
    self.invitation_created_at = Time.now.utc
    self.invitation_sent_at = self.invitation_created_at unless skip_invitation
    self.invited_by = invited_by if invited_by

    # Call these before_validate methods since we aren't validating on save
    self.downcase_keys if new_record_and_responds_to?(:downcase_keys)
    self.strip_whitespace if new_record_and_responds_to?(:strip_whitespace)

    validate = options.key?(:validate) ? options[:validate] : self.class.validate_on_invite
    if save(validate: validate)
      self.invited_by.decrement_invitation_limit! if !was_invited and self.invited_by.present?
      deliver_invitation(options) unless skip_invitation
    end
  end
end

#invited_to_sign_up? ⇒ Boolean

Verifies whether a user has been invited or not

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/devise_invitable/models.rb', line 119

def invited_to_sign_up?
  accepting_invitation? || (persisted? && invitation_token.present?)
end

#password_required? ⇒ Boolean

Enforce password when invitation is being accepted

Returns:

  • (Boolean) 


187
188
189
 
# File 'lib/devise_invitable/models.rb', line 187

def password_required?
  (accepting_invitation? && self.class.require_password_on_accepting) || super
end

#rollback_accepted_invitation ⇒ Object 



107
108
109
110
111
 
# File 'lib/devise_invitable/models.rb', line 107

def rollback_accepted_invitation
  self.invitation_token = self.invitation_token_was
  self.invitation_accepted_at = nil
  self.confirmed_at = nil if self.respond_to?(:confirmed_at=)
end

#send_password_change_notification? ⇒ Boolean

Prevent password changed email when accepting invitation

Returns:

  • (Boolean) 


182
183
184
 
# File 'lib/devise_invitable/models.rb', line 182

def send_password_change_notification?
  super && !accepting_invitation?
end

#unauthenticated_message ⇒ Object 



191
192
193
 
# File 'lib/devise_invitable/models.rb', line 191

def unauthenticated_message
  block_from_invitation? ? :invited : super
end

#valid_invitation? ⇒ Boolean

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.

Returns:

  • (Boolean) 


172
173
174
 
# File 'lib/devise_invitable/models.rb', line 172

def valid_invitation?
  invited_to_sign_up? && invitation_period_valid?
end

#valid_password?(password) ⇒ Boolean

Only verify password when is not invited

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/devise_invitable/models.rb', line 177

def valid_password?(password)
  super unless !accepting_invitation? && block_from_invitation?
end