Module: PublicActivity::Common

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

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_hooksHash<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_keyString

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_ownerModel

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_globalModel

Global version of activity owner

Returns:

See Also:


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

#activity_paramsHash<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_globalHash<Symbol, Object>

Global version of activity parameters

Returns:

  • (Hash<Symbol, Object>)

See Also:


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

#activity_recipientModel

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_globalModel

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)

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


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

def call_hook_safe(key)
  hook = self.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


250
251
252
253
254
255
256
257
258
259
260
# File 'lib/public_activity/common.rb', line 250

def create_activity(*args)
  return unless self.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:


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

def create_activity!(*args)
  return unless self.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
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 PublicActivity::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


172
173
174
# File 'lib/public_activity/common.rb', line 172

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!(self.activity_custom_fields) if self.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] ||
    self.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!(self.activity_params) if self.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.has_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


163
164
165
# File 'lib/public_activity/common.rb', line 163

def public_activity_enabled?
  PublicActivity.enabled?
end

#reset_activity_instance_optionsObject

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