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 ⇒ Object

Returns the value of attribute activity_account.



77
78
79
 
# File 'lib/wiser_trails/common.rb', line 77

def 
  @activity_account
end

#activity_account_global ⇒ Model

Global version of activity recipient

Returns:

See Also:




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

#activity_custom_fields ⇒ Object

Returns the value of attribute activity_custom_fields.



81
82
83
 
# File 'lib/wiser_trails/common.rb', line 81

def activity_custom_fields
  @activity_custom_fields
end

#activity_force_fields_global ⇒ Object

Returns the value of attribute activity_force_fields_global.



85
86
87
 
# File 'lib/wiser_trails/common.rb', line 85

def activity_force_fields_global
  @activity_force_fields_global
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 49

#activity_key ⇒ Object

Returns the value of attribute activity_key.



79
80
81
 
# File 'lib/wiser_trails/common.rb', line 79

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>) 


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

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 44

#activity_owner ⇒ Object

Returns the value of attribute activity_owner.



75
76
77
 
# File 'lib/wiser_trails/common.rb', line 75

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 34

#activity_skip_fields_global ⇒ Object

Returns the value of attribute activity_skip_fields_global.



83
84
85
 
# File 'lib/wiser_trails/common.rb', line 83

def activity_skip_fields_global
  @activity_skip_fields_global
end

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)

Returns:

  • (Boolean) —

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

Since:

  • 0.4.0



143
144
145
146
147
148
149
150
151
 
# File 'lib/wiser_trails/common.rb', line 143

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



210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/wiser_trails/common.rb', line 210

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



283
284
285
286
287
 
# File 'lib/wiser_trails/common.rb', line 283

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) ⇒ Object

Shortcut for WiserTrails::Common::ClassMethods#get_hook



132
133
134
 
# File 'lib/wiser_trails/common.rb', line 132

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:



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/wiser_trails/common.rb', line 233

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.



293
294
295
296
297
298
299
300
301
302
 
# File 'lib/wiser_trails/common.rb', line 293

def reset_activity_instance_options
  @activity_old_value = {}
  @activity_new_value = {}
  @activity_key = nil
  @activity_owner = nil
  @activity_account = nil
  @activity_custom_fields = {}
  @activity_skip_fields_global = {}
  @activity_force_fields_global = {}
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



123
124
125
 
# File 'lib/wiser_trails/common.rb', line 123

def wiser_trails_enabled?
  WiserTrails.enabled?
end