Module: WiserTrails::Common

Extended by:
ActiveSupport::Concern
Defined in:
lib/wiser_trails/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

#activity_account ⇒ Model

Set or get recipient for activity.

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/wiser_trails/common.rb', line 97

def 
  @activity_account
end

#activity_account_global ⇒ Model

Global version of activity recipient

Returns:

See Also:




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

#activity_custom_fields ⇒ Hash

Set or get custom fields for later processing

Returns:

  • (Hash) 


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

def activity_custom_fields
  @activity_custom_fields
end

#activity_hooks ⇒ Hash<Symbol, Proc>

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

The supported keys are:

  • :create

  • :update

  • :destroy

Returns:

  • (Hash<Symbol, Proc>) 



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

#activity_key ⇒ String

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

Usage:

@article = Article.new
@article.activity_key = "my.custom.article.key"
@article.save
@article.activities.last.key #=> "my.custom.article.key"

Returns:

  • (String) 


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

def activity_key
  @activity_key
end

#activity_new_value ⇒ Hash<Symbol, Object>

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

Usage:

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

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

Returns:

  • (Hash<Symbol, Object>) 


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

def activity_new_value
  @activity_new_value
end

#activity_new_value_global ⇒ Hash<Symbol, Object>

Global version of activity parameters

Returns:

  • (Hash<Symbol, Object>)

See Also:




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

#activity_owner ⇒ Model

Set or get owner object responsible for the Activity.

Usage:

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

Returns:

  • (Model) —

    Polymorphic model

See Also:



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

def activity_owner
  @activity_owner
end

#activity_owner_global ⇒ Model

Global version of activity owner

Returns:

See Also:




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

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/wiser_trails/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, WiserTrails.get_controller)
  else
    true
  end
end

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

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

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

current_user.create_activity(:avatar_changed)

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

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

@article.activity :owner => proc {|controller| controller.current_user }
@article.create_activity(: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_activity :commented_on
@article.activities.last.key # => "article.commented_on"

For other parameters, see Tracked#activity, and “Instance options” accessors at Tracked, information on hooks is available at Tracked::ClassMethods#tracked.

Overloads:

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

    Parameters:

    • action (Symbol, String) —

      Name of the action

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

      Options with quality higher than instance options set in Tracked#activity

    Options Hash (options):

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

    Parameters:

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

      Options with quality higher than instance options set in Tracked#activity

    Options Hash (options):

Returns:

  • (Model, nil) —

    If created successfully, new activity

See Also:

Since:

  • 0.4.0



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

def create_activity(*args)
  return unless self.wiser_trails_enabled?
  options = prepare_settings(*args)

  if call_hook_safe(options[:key].split('.').last)
    reset_activity_instance_options
    return WiserTrails::Adapter.create_activity(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



321
322
323
324
325
 
# File 'lib/wiser_trails/common.rb', line 321

def extract_key(action, options = {})
  (options[:key] || self.activity_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 WiserTrails::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/wiser_trails/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 Activity record. params passed directly to tracked model have priority over settings specified in tracked() 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
 
# File 'lib/wiser_trails/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)
  }
  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 activity
  options[:owner] = WiserTrails.resolve_value(self,
    (all_options.has_key?(:owner) ? all_options[:owner] : (
      self.activity_owner || self.class.activity_owner_global
      )
    )
  )

  # recipient of the activity
  options[:account] = WiserTrails.resolve_value(self,
    (all_options.has_key?(:account) ? all_options[:account] : (
      self. || self.class.
      )
    )
  )

  changes = Hash.new
  self.changed_attributes.each do |attr, val|
    changes[attr.to_sym] = val if attr != "updated_at"
  end
  options[:old_value] = changes.stringify_keys
  options.delete(:params)

  customs = self.class.activity_custom_fields_global.clone
  customs.merge!(self.activity_custom_fields) if self.activity_custom_fields
  customs.merge!(all_options)
  customs.each do  |k, v|
    customs[k] = WiserTrails.resolve_value(self, v)
  end.merge options
end

#reset_activity_instance_options ⇒ Object

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



331
332
333
334
335
336
337
338
 
# File 'lib/wiser_trails/common.rb', line 331

def reset_activity_instance_options
  @activity_old_value = {}
  @activity_new_value = {}
  @activity_key = nil
  @activity_owner = nil
  @activity_account = nil
  @activity_custom_fields = {}
end

#wiser_trails_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 WiserTrails is enabled globally and for this class.

Returns:

  • (Boolean)

Since:

  • 0.5.0



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

def wiser_trails_enabled?
  WiserTrails.enabled?
end