Module: PublicActivity::Common

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

Overview

Common methods shared across the gem.

Global options collapse

Instance options collapse

Instance Method Summary collapse

Instance Attribute Details

#activity_custom_fields ⇒ Hash

Set or get custom fields for later processing

Returns:

  • (Hash) 


117
118
119
 
# File 'lib/public_activity/common.rb', line 117

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/public_activity/common.rb', line 50

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


111
112
113
 
# File 'lib/public_activity/common.rb', line 111

def activity_key
  @activity_key
end

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



90
91
92
 
# File 'lib/public_activity/common.rb', line 90

def activity_owner
  @activity_owner
end

#activity_owner_global ⇒ Model

Global version of activity owner

Returns:

See Also:




# File 'lib/public_activity/common.rb', line 35

#activity_params ⇒ Hash<Symbol, Object>

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

Usage:

@article.activity_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 Activity.

Returns:

  • (Hash<Symbol, Object>) 


74
75
76
 
# File 'lib/public_activity/common.rb', line 74

def activity_params
  @activity_params
end

#activity_params_global ⇒ Hash<Symbol, Object>

Global version of activity parameters

Returns:

  • (Hash<Symbol, Object>)

See Also:




# File 'lib/public_activity/common.rb', line 45

#activity_recipient ⇒ 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



99
100
101
 
# File 'lib/public_activity/common.rb', line 99

def activity_recipient
  @activity_recipient
end

#activity_recipient_global ⇒ Model

Global version of activity recipient

Returns:

See Also:




# File 'lib/public_activity/common.rb', line 40

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



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

def call_hook_safe(key)
  hook = get_hook(key)
  if hook
    # provides hook with model and controller
    hook.call(self, PublicActivity.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
259
 
# File 'lib/public_activity/common.rb', line 248

def create_activity(*args)
  return unless public_activity_enabled?

  options = prepare_settings(*args)

  if call_hook_safe(options[:key].split('.').last)
    reset_activity_instance_options
    return PublicActivity::Adapter.create_activity(self, options)
  end

  nil
end

#create_activity!(*args) ⇒ Object

Directly saves activity to database. Works the same as create_activity but throws validation error for each supported ORM.

See Also:



265
266
267
268
269
270
271
272
273
274
 
# File 'lib/public_activity/common.rb', line 265

def create_activity!(*args)
  return unless public_activity_enabled?

  options = prepare_settings(*args)

  if call_hook_safe(options[:key].split('.').last)
    reset_activity_instance_options
    PublicActivity::Adapter.create_activity!(self, options)
  end
end

#get_hook(key) ⇒ Object

Shortcut for ClassMethods#get_hook



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

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

#prepare_custom_fields(options) ⇒ Object

Prepares and resolves custom fields users can pass to ‘tracked` method



307
308
309
310
311
312
313
314
 
# File 'lib/public_activity/common.rb', line 307

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

#prepare_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



343
344
345
346
347
348
349
 
# File 'lib/public_activity/common.rb', line 343

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

#prepare_parameters(options) ⇒ Object

Prepares i18n parameters that will be serialized into the Activity#parameters column



319
320
321
322
323
324
325
 
# File 'lib/public_activity/common.rb', line 319

def prepare_parameters(options)
  params = {}
  params.merge!(self.class.activity_params_global)
  params.merge!(activity_params) if activity_params
  params.merge!([options.delete(:parameters), options.delete(:params), {}].compact.first)
  params.each { |k, v| params[k] = PublicActivity.resolve_value(self, v) }
end

#prepare_relation(name, options) ⇒ Object

Prepares relation to be saved to Activity. Can be :recipient or :owner



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

def prepare_relation(name, options)
  PublicActivity.resolve_value(self,
    (options.key?(name) ? options[name] : (
      self.send("activity_#{name}") || self.class.send("activity_#{name}_global")
      )
    )
  )
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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/public_activity/common.rb', line 287

def prepare_settings(*args)
  raw_options = args.extract_options!
  action      = [args.first, raw_options.delete(:action)].compact.first
  key         = prepare_key(action, raw_options)

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

  prepare_custom_fields(raw_options.except(:params)).merge(
    {
      key:        key,
      owner:      prepare_relation(:owner,     raw_options),
      recipient:  prepare_relation(:recipient, raw_options),
      parameters: prepare_parameters(raw_options),
    }
  )
end

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

Returns:

  • (Boolean)

Since:

  • 0.5.0



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

def public_activity_enabled?
  PublicActivity.enabled?
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.



355
356
357
358
359
360
361
 
# File 'lib/public_activity/common.rb', line 355

def reset_activity_instance_options
  @activity_params = {}
  @activity_key = nil
  @activity_owner = nil
  @activity_recipient = nil
  @activity_custom_fields = {}
end