Module: ActivityNotification::ActsAsNotifiable

Extended by:
ActiveSupport::Concern
Included in:
Models
Defined in:
lib/activity_notification/roles/acts_as_notifiable.rb

Overview

Manages to add all required configurations to notifiable models.

Class Method Summary collapse

Class Method Details

.acts_as_notifiable(target_type, options = {}) ⇒ Hash

Adds required configurations to notifiable models.

Parameters:

  • :targets

    • Targets to send notifications. It it set as ActiveRecord records or array of models. This is a only necessary option. If you do not specify this option, you have to override notification_targets or notification_[plural target type] (e.g. notification_users) method.

  • :group

    • Group unit of notifications. Notifications will be bundled by this group (and target, notifiable_type, key). This parameter is a optional.

  • :group_expiry_delay

    • Expiry period of a notification group. Notifications will be bundled within the group expiry period. This parameter is a optional.

  • :notifier

    • Notifier of the notification. This will be stored as notifier with notification record. This parameter is a optional.

  • :parameters

    • Additional parameters of the notifications. This will be stored as parameters with notification record. You can use these additional parameters in your notification view or i18n text. This parameter is a optional.

  • :email_allowed

    • Whether activity_notification sends notification email. Specified method or symbol is expected to return true (not nil) or false (nil). This parameter is a optional since default value is false. To use notification email, email_allowed option must return true (not nil) in both of notifiable and target model. This can be also configured default option in initializer.

  • :notifiable_path

    • Path to redirect from open or move action of notification controller. You can also use this notifiable_path as notifiable link in notification view. This parameter is a optional since polymorphic_path is used as default value.

  • :tracked

    • Adds required callbacks to generate notifications for creation and update of the notifiable model. Tracked notifications are disabled as default. When you set true as this :tracked option, default callbacks will be enabled for [:create, :update]. You can use :only, :except and other notify options as hash for this option.

  • :printable_name or :printable_notifiable_name

    • Printable notifiable name. This parameter is a optional since ‘ActivityNotification::Common.printable_name` is used as default value. :printable_name is the same option as :printable_notifiable_name

  • :dependent_notifications

    • Dependency for notifications to delete generated notifications with this notifiable. This option is used to configure generated_notifications_as_notifiable association. You can use :delete_all, :destroy, :restrict_with_error, :restrict_with_exception, :update_group_and_delete_all or :update_group_and_destroy for this option. When you use :update_group_and_delete_all or :update_group_and_destroy to this parameter, the oldest group member notification becomes a new group owner as ‘before_destroy` of this Notifiable. This parameter is effective for all target and is a optional since no dependent option is used as default.

  • :optional_targets

    • Optional targets to integrate external notification serveces like Amazon SNS or Slack. You can use hash of optional target implementation class as key and initializing parameters as value for this parameter. When the hash parameter is passed, acts_as_notifiable will create new instance of optional target class and call initialize_target method with initializing parameters, then configure them as optional_targets for this notifiable and target. You can also use symbol of method name or lambda function which returns array of initialized optional target intstances. All optional target class must extends ActivityNotification::OptionalTarget::Base. This parameter is completely optional.

Examples:

Notify to all users

class Comment < ActiveRecord::Base
  acts_as_notifiable :users, targets: User.all
end

Notify to author and users commented to the article, except comment owner self

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  belongs_to :user
  acts_as_notifiable :users,
    targets: ->(comment, key) {
      ([comment.article.user] + comment.article.commented_users.to_a - [comment.user]).uniq
    }
end

All unopened notifications to the same target will be grouped by ‘article`

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  acts_as_notifiable :users, targets: User.all, group: :article
end

All unopened notifications to the same target within 1 day will be grouped by ‘article`

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  acts_as_notifiable :users, targets: User.all, group: :article, :group_expiry_delay: 1.day
end

Set comment owner self as notifier

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  belongs_to :user
  acts_as_notifiable :users, targets: User.all, notifier: :user
end

Set constant values as additional parameter

# app/models/comment.rb
class Comment < ActiveRecord::Base
  acts_as_notifiable :users, targets: User.all, parameters: { default_param: '1' }
end

Set comment body as additional parameter

# app/models/comment.rb
class Comment < ActiveRecord::Base
  acts_as_notifiable :users, targets: User.all, parameters: ->(comment, key) { body: comment.body }
end

Enable email notification for this notifiable model

# app/models/comment.rb
class Comment < ActiveRecord::Base
  acts_as_notifiable :users, targets: User.all, email_allowed: true
end

Redirect to parent article page from comment notifications

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  acts_as_notifiable :users, targets: User.all, notifiable_path: :article_notifiable_path

  def article_notifiable_path
    article_path(article)
  end
end

Add all callbacks to generate notifications for creation and update

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  acts_as_notifiable :users, targets: User.all, tracked: true
end

Add callbacks to generate notifications for creation only

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  acts_as_notifiable :users, targets: User.all, tracked: { only: [:create] }
end

Add callbacks to generate notifications for creation (except update) only

# app/models/comment.rb
class Comment < ActiveRecord::Base
  belongs_to :article
  acts_as_notifiable :users, targets: User.all, tracked: { except: [:update], key: "comment.edited", send_later: false }
end

Define printable name with comment body

# app/models/comment.rb
class Comment < ActiveRecord::Base
  acts_as_notifiable :users, targets: User.all, printable_name: ->(comment) { "comment \"#{comment.body}\"" }
end

Define :delete_all dependency to generated notifications

# app/models/comment.rb
class Comment < ActiveRecord::Base
  acts_as_notifiable :users, targets: User.all, dependent_notifications: :delete_all
end

Define to integrate with Amazon SNS, Slack and your custom ConsoleOutput targets

# app/models/comment.rb
class Comment < ActiveRecord::Base
  require 'activity_notification/optional_targets/amazon_sns'
  require 'activity_notification/optional_targets/slack'
  require 'custom_optional_targets/console_output'
  acts_as_notifiable :admins, targets: Admin.all,
    optional_targets: {
      ActivityNotification::OptionalTarget::AmazonSNS => { topic_arn: '<Topin ARN of yours>' },
      ActivityNotification::OptionalTarget::Slack  => {
        webhook_url: '<Slack Webhook URL>',
        slack_name: :slack_name, channel: 'activity_notification', username: 'ActivityNotification', icon_emoji: ":ghost:"
      },
      CustomOptionalTarget::ConsoleOutput => {}
    }
end

Parameters:

  • target_type (Symbol) —

    Type of notification target as symbol

  • options (Hash) (defaults to: {}) —

    Options for notifiable model configuration

Options Hash (options):

  • :targets (Symbol, Proc, Array) — default: nil —

    Targets to send notifications

  • :group (Symbol, Proc, Object) — default: nil —

    Group unit of the notifications

  • :group_expiry_delay (Symbol, Proc, Object) — default: nil —

    Expiry period of a notification group

  • :notifier (Symbol, Proc, Object) — default: nil —

    Notifier of the notifications

  • :parameters (Symbol, Proc, Hash) — default: {} —

    Additional parameters of the notifications

  • :email_allowed (Symbol, Proc, Boolean) — default: ActivityNotification.config.email_enabled —

    Whether activity_notification sends notification email

  • :notifiable_path (Symbol, Proc, String) — default: polymorphic_path(self) —

    Path to redirect from open or move action of notification controller

  • :tracked (Boolean, Hash) — default: nil —

    Flag or parameters for automatic tracked notifications

  • :printable_name (Symbol, Proc, String) — default: ActivityNotification::Common.printable_name —

    Printable notifiable name

  • :dependent_notifications (Symbol, Proc) — default: nil —

    Dependency for notifications to delete generated notifications with this notifiable, [:delete_all, :destroy, :restrict_with_error, :restrict_with_exception, :update_group_and_delete_all, :update_group_and_destroy] are available

  • :optional_targets (Hash<Class, Hash>) — default: nil —

    Optional target configurations with hash of ‘OptionalTarget` implementation class as key and initializing option parameter as value

Returns:

  • (Hash) —

    Configured parameters as notifiable model



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 197

def acts_as_notifiable(target_type, options = {})
  include Notifiable
  configured_params = {}

  if options[:tracked].present?
    configured_params.update(add_tracked_callbacks(target_type, options[:tracked].is_a?(Hash) ? options[:tracked] : {}))
  end

  if available_dependent_notifications_options.include? options[:dependent_notifications]
    configured_params.update(add_destroy_dependency(target_type, options[:dependent_notifications]))
  end

  if options[:optional_targets].is_a?(Hash)
    options[:optional_targets] = arrange_optional_targets_option(options[:optional_targets])
  end

  options[:printable_notifiable_name] ||= options.delete(:printable_name)
  configured_params
    .merge set_acts_as_parameters_for_target(target_type, [:targets, :group, :group_expiry_delay, :parameters, :email_allowed], options, "notification_")
    .merge set_acts_as_parameters_for_target(target_type, [:notifier, :notifiable_path, :printable_notifiable_name, :optional_targets], options)
end

.add_destroy_dependency(target_type, dependent_notifications_option) ⇒ Hash<Symbol, Symbol>

Adds destroy dependency.

Parameters:

  • target_type (Symbol) —

    Type of notification target as symbol

  • dependent_notifications_option (Symbol) —

    Specified :dependent_notifications option

Returns:

  • (Hash<Symbol, Symbol>) —

    Configured dependency options



287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 287

def add_destroy_dependency(target_type, dependent_notifications_option)
  case dependent_notifications_option
  when :delete_all, :destroy, :restrict_with_error, :restrict_with_exception
    before_destroy -> { destroy_generated_notifications_with_dependency(dependent_notifications_option, target_type) }
  when :update_group_and_delete_all
    before_destroy -> { destroy_generated_notifications_with_dependency(:delete_all, target_type, true) }
  when :update_group_and_destroy
    before_destroy -> { destroy_generated_notifications_with_dependency(:destroy, target_type, true) }
  end
  { dependent_notifications: dependent_notifications_option }
end

.add_tracked_callback(tracked_callbacks, tracked_action, tracked_proc) ⇒ Object

Adds tracked callback.

Parameters:

  • tracked_callbacks (Array<Symbol>) —

    Array of tracked callbacks (Array of [:create or :update])

  • tracked_action (Symbol) —

    Tracked action (:create or :update)

  • tracked_proc (Proc) —

    Proc or lambda function to execute



272
273
274
275
276
277
278
279
280
281
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 272

def add_tracked_callback(tracked_callbacks, tracked_action, tracked_proc)
  if tracked_callbacks.include? tracked_action
    case tracked_action
    when :create
      after_create tracked_proc
    when :update
      after_update tracked_proc
    end
  end
end

.add_tracked_callbacks(target_type, tracked_option = {}) ⇒ Hash<Symbol, Symbol>

Adds tracked callbacks.

Parameters:

  • target_type (Symbol) —

    Type of notification target as symbol

  • tracked_option (Hash) (defaults to: {}) —

    Specified :tracked option

Returns:

  • (Hash<Symbol, Symbol>) —

    Configured tracked callbacks options



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 251

def add_tracked_callbacks(target_type, tracked_option = {})
  tracked_callbacks = [:create, :update]
  if tracked_option[:except]
    tracked_callbacks -= tracked_option.delete(:except)
  elsif tracked_option[:only]
    tracked_callbacks &= tracked_option.delete(:only)
  end
  if tracked_option.has_key?(:key)
    add_tracked_callback(tracked_callbacks, :create, ->{ notify target_type, tracked_option })
    add_tracked_callback(tracked_callbacks, :update, ->{ notify target_type, tracked_option })
  else
    add_tracked_callback(tracked_callbacks, :create, ->{ notify target_type, tracked_option.merge(key: notification_key_for_tracked_creation) })
    add_tracked_callback(tracked_callbacks, :update, ->{ notify target_type, tracked_option.merge(key: notification_key_for_tracked_update) })
  end
  { tracked: tracked_callbacks }
end

.arrange_optional_targets_option(optional_targets_option) ⇒ Hash<ActivityNotification::OptionalTarget::Base, Hash>

Arrange optional targets option.

Parameters:

  • optional_targets_option (Symbol) —

    Specified :optional_targets option

Returns:



302
303
304
305
306
307
308
309
310
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 302

def arrange_optional_targets_option(optional_targets_option)
  optional_targets_option.map { |target_class, target_options|
    optional_target = target_class.new(target_options)
    unless optional_target.kind_of?(ActivityNotification::OptionalTarget::Base)
      raise TypeError, "#{optional_target.class.name} for an optional target is not a kind of ActivityNotification::OptionalTarget::Base"
    end
    optional_target
  }
end

.available_dependent_notifications_options ⇒ Array<Symbol>

Returns array of available notifiable options in acts_as_notifiable.

Returns:

  • (Array<Symbol>) —

    Array of available notifiable options



237
238
239
240
241
242
243
244
245
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 237

def available_dependent_notifications_options
  [ :delete_all,
    :destroy,
    :restrict_with_error,
    :restrict_with_exception,
    :update_group_and_delete_all,
    :update_group_and_destroy
  ].freeze
end

.available_notifiable_options ⇒ Array<Symbol>

Returns array of available notifiable options in acts_as_notifiable.

Returns:

  • (Array<Symbol>) —

    Array of available notifiable options



221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 221

def available_notifiable_options
  [ :targets,
    :group,
    :group_expiry_delay,
    :notifier,
    :parameters,
    :email_allowed,
    :notifiable_path,
    :printable_notifiable_name, :printable_name,
    :dependent_notifications,
    :optional_targets
  ].freeze
end