Module: UserNotification::Common

Extended by:
ActiveSupport::Concern
Defined in:
lib/user_notification/common.rb

Overview

Common methods shared across the gem.

Defined Under Namespace

Modules: ClassMethods

Global options collapse

Instance options collapse

Instance Method Summary collapse

Instance Attribute Details

#notification_custom_fields ⇒ Hash

Set or get custom fields for later processing

Returns:

  • (Hash) 


115
116
117
 
# File 'lib/user_notification/common.rb', line 115

def notification_custom_fields
  @notification_custom_fields
end

#notification_hooks ⇒ Hash<Symbol, Proc>

Hooks/functions that will be used to decide if the notification should get created.

The supported keys are:

  • :create

  • :update

  • :destroy

Returns:

  • (Hash<Symbol, Proc>) 



# File 'lib/user_notification/common.rb', line 48

#notification_key ⇒ String

Set or get custom i18n key passed to Notification, later used in Renderable#text

Usage:

@article = Article.new
@article.notification_key = "my.custom.article.key"
@article.save
@article.notifications.last.key #=> "my.custom.article.key"

Returns:

  • (String) 


109
110
111
 
# File 'lib/user_notification/common.rb', line 109

def notification_key
  @notification_key
end

#notification_owner ⇒ Model

Set or get owner object responsible for the Notification.

Usage:

# where current_user is an object of logged in user
@article.notification_owner = current_user
# OR: take @article.author association
@article.notification_owner = :author
# OR: provide a Proc with custom code
@article.notification_owner = proc {|controller, model| model.author }
@article.save
@article.notifications.last.owner #=> Returns owner object

Returns:

  • (Model) —

    Polymorphic model

See Also:



88
89
90
 
# File 'lib/user_notification/common.rb', line 88

def notification_owner
  @notification_owner
end

#notification_owner_global ⇒ Model

Global version of notification owner

Returns:

See Also:




# File 'lib/user_notification/common.rb', line 33

#notification_params ⇒ Hash<Symbol, Object>

Set or get parameters that will be passed to Notification when saving

Usage:

@article.notification_params = {:article_title => @article.title}
@article.save

This way you can pass strings that should remain constant, even when model attributes change after creating this Notification.

Returns:

  • (Hash<Symbol, Object>) 


72
73
74
 
# File 'lib/user_notification/common.rb', line 72

def notification_params
  @notification_params
end

#notification_params_global ⇒ Hash<Symbol, Object>

Global version of notification parameters

Returns:

  • (Hash<Symbol, Object>)

See Also:




# File 'lib/user_notification/common.rb', line 43

#notification_recipient ⇒ Model

Set or get recipient for notification.

Association is polymorphic, thus allowing assignment of all types of models. This can be used for example in the case of sending private notifications for only a single user.

Returns:

  • (Model) —

    Polymorphic model



97
98
99
 
# File 'lib/user_notification/common.rb', line 97

def notification_recipient
  @notification_recipient
end

#notification_recipient_global ⇒ Model

Global version of notification recipient

Returns:

See Also:




# File 'lib/user_notification/common.rb', line 38

Instance Method Details

#call_hook_safe(key) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Calls hook safely. If a hook for given action exists, calls it with model (self) and controller (if available, see StoreController)

Parameters:

  • key (String, Symbol) —

    action to retrieve a hook for

Returns:

  • (Boolean) —

    if hook exists, it’s decision, if there’s no hook, true

Since:

  • 0.4.0



181
182
183
184
185
186
187
188
189
 
# File 'lib/user_notification/common.rb', line 181

def call_hook_safe(key)
  hook = self.get_hook(key)
  if hook
    # provides hook with model and controller
    hook.call(self, UserNotification.get_controller)
  else
    true
  end
end

#create_notification(action, options = {}) ⇒ Model? #create_notification(options = {}) ⇒ Model?

Directly creates notification record in the database, based on supplied options.

It’s meant for creating custom notifications while preserving all configuration defined before. If you fire up the simplest of options:

current_user.create_notification(:avatar_changed)

It will still gather data from any procs or symbols you passed as params to Notifiable::ClassMethods#notifiable. It will ask the hooks you defined whether to really save this notification.

But you can also overwrite instance and global settings with your options:

@article.notification :owner => proc {|controller| controller.current_user }
@article.create_notification(:commented_on, :owner => @user)

And it’s smart! It won’t execute your proc, since you’ve chosen to overwrite instance parameter :owner with @user.

:key

The key will be generated from either:

  • the first parameter you pass that is not a hash (action)

  • the :action option in the options hash (action)

  • the :key option in the options hash (it has to be a full key, including model name)

When you pass an action (first two options above), they will be added to parameterized model name:

Given Article model and instance: @article,

@article.create_notification :commented_on
@article.notifications.last.key # => "article.commented_on"

For other parameters, see Notifiable#notification, and “Instance options” accessors at Notifiable, information on hooks is available at Notifiable::ClassMethods#notifiable.

Overloads:

  • #create_notification(action, options = {}) ⇒ Model?

    Parameters:

    • action (Symbol, String) —

      Name of the action

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

      Options with quality higher than instance options set in Notifiable#notification

    Options Hash (options):

  • #create_notification(options = {}) ⇒ Model?

    Parameters:

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

      Options with quality higher than instance options set in Notifiable#notification

    Options Hash (options):

Returns:

  • (Model, nil) —

    If created successfully, new notification

See Also:

Since:

  • 0.4.0



248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/user_notification/common.rb', line 248

def create_notification(*args)
  return unless self.user_notification_enabled?
  options = prepare_settings(*args)

  if call_hook_safe(options[:key].split('.').last)
    reset_notification_instance_options
    return UserNotification::Adapter.create_notification(self, options)
  end

  nil
end

#extract_key(action, options = {}) ⇒ String

Helper method to serialize class name into relevant key

Parameters:

  • or (Symbol) —
    String

    the name of the operation to be done on class

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

    to be used on key generation, defaults to {}

Returns:

  • (String) —

    the resulted key



324
325
326
327
328
 
# File 'lib/user_notification/common.rb', line 324

def extract_key(action, options = {})
  (options[:key] || self.notification_key ||
    ((self.class.name.underscore.gsub('/', '_') + "." + action.to_s) if action)
  ).try(:to_s)
end

#get_hook(key) ⇒ Proc?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Shortcut for UserNotification::Common::ClassMethods#get_hook

Parameters:

  • key (String, Symbol) —

    action to retrieve a hook for

Returns:

  • (Proc, nil) —

    callable hook or nil

Since:

  • 0.4.0



170
171
172
 
# File 'lib/user_notification/common.rb', line 170

def get_hook(key)
  self.class.get_hook(key)
end

#prepare_settings(action, options = {}) ⇒ Hash #prepare_settings(options = {}) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Prepares settings used during creation of Notification record. params passed directly to notifiable model have priority over settings specified in notifiable() method

Overloads:

Returns:

  • (Hash) —

    Settings with preserved options that were passed

Raises:

See Also:



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/user_notification/common.rb', line 271

def prepare_settings(*args)
  # key
  all_options = args.extract_options!
  options = {
    key: all_options.delete(:key),
    action: all_options.delete(:action),
    parameters: all_options.delete(:parameters) || all_options.delete(:params)
  }
  action = (args.first || options[:action]).try(:to_s)

  options[:key] = extract_key(action, options)

  raise NoKeyProvided, "No key provided for #{self.class.name}" unless options[:key]

  options.delete(:action)

  # user responsible for the notification
  options[:owner] = UserNotification.resolve_value(self,
    (all_options.has_key?(:owner) ? all_options[:owner] : (
      self.notification_owner || self.class.notification_owner_global
      )
    )
  )

  # recipient of the notification
  options[:recipient] = UserNotification.resolve_value(self,
    (all_options.has_key?(:recipient) ? all_options[:recipient] : (
      self.notification_recipient || self.class.notification_recipient_global
      )
    )
  )

  #customizable parameters
  params = {}
  params.merge!(self.class.notification_params_global)
  params.merge!(self.notification_params) if self.notification_params
  params.merge!(options[:params] || options[:parameters] || {})
  params.each { |k, v| params[k] = UserNotification.resolve_value(self, v) }
  options[:parameters] = params
  options.delete(:params)

  customs = self.class.notification_custom_fields_global.clone
  customs.merge!(self.notification_custom_fields) if self.notification_custom_fields
  customs.merge!(all_options)
  customs.each do  |k, v|
    customs[k] = UserNotification.resolve_value(self, v)
  end.merge options
end

#reset_notification_instance_options ⇒ Object

Resets all instance options on the object triggered by a successful #create_notification, should not be called from any other place, or from application code.



334
335
336
337
338
339
340
 
# File 'lib/user_notification/common.rb', line 334

def reset_notification_instance_options
  @notification_params = {}
  @notification_key = nil
  @notification_owner = nil
  @notification_recipient = nil
  @notification_custom_fields = {}
end

#user_notification_enabled? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if UserNotification is enabled globally and for this class.

Returns:

  • (Boolean)

Since:

  • 0.5.0



161
162
163
 
# File 'lib/user_notification/common.rb', line 161

def user_notification_enabled?
  UserNotification.enabled?
end