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.
  • :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

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

  • :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



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 167

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

  if [:delete_all, :destroy, :restrict_with_error, :restrict_with_exception, :update_group_and_delete_all, :update_group_and_destroy].include? options[:dependent_notifications]
    case options[:dependent_notifications]
    when :delete_all, :destroy, :restrict_with_error, :restrict_with_exception
      has_many_generated_notifications options[:dependent_notifications]
    when :update_group_and_delete_all
      before_destroy :remove_generated_notifications_from_group
      has_many_generated_notifications :delete_all
    when :update_group_and_destroy
      before_destroy :remove_generated_notifications_from_group
      has_many_generated_notifications :destroy
    end
    configured_params = { dependent_notifications: options[:dependent_notifications] }
  end

  if options[:optional_targets].is_a?(Hash)
    options[:optional_targets] = options[:optional_targets].map { |target_class, target_options|
      optional_target = target_class.new
      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.initialize_target(target_options)
      optional_target
    }
  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

.available_notifiable_options ⇒ Array<Symbol>

Returns array of available notifiable options in acts_as_notifiable.

Returns:

  • (Array<Symbol>) —

    Array of available notifiable options



204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/activity_notification/roles/acts_as_notifiable.rb', line 204

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