module PublicActivity::Common

Common methods shared across the gem.

Attributes

activity_custom_fields[RW]

Set or get custom fields for later processing

@return [Hash]

activity_key[RW]

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"

@return [String]

activity_owner[RW]

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

@return [Model] Polymorphic model @see activity_owner_global

activity_params[RW]

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}. @return [Hash<Symbol, Object>]

activity_recipient[RW]

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. @return (see activity_owner)

Public Instance Methods

call_hook_safe(key) click to toggle source

Calls hook safely. If a hook for given action exists, calls it with model (self) and controller (if available, see {StoreController}) @param key (see get_hook) @return [Boolean] if hook exists, it's decision, if there's no hook, true @since 0.4.0 @api private

# 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(*args) click to toggle source

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}. @see prepare_settings @return [Model, nil] If created successfully, new activity @since 0.4.0 @api public @overload create_activity(action, options = {})

@param [Symbol,String] action Name of the action
@param [Hash] options Options with quality higher than instance options
  set in {Tracked#activity}
@option options [Activist] :owner Owner
@option options [Activist] :recipient Recipient
@option options [Hash] :params Parameters, see
  {PublicActivity.resolve_value}

@overload create_activity(options = {})

@param [Hash] options Options with quality higher than instance options
  set in {Tracked#activity}
@option options [Symbol,String] :action Name of the action
@option options [String] :key Full key
@option options [Activist] :owner Owner
@option options [Activist] :recipient Recipient
@option options [Hash] :params Parameters, see
  {PublicActivity.resolve_value}
# 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) click to toggle source

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

@see create_activity

# 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) click to toggle source

Shortcut for {ClassMethods#get_hook} @param (see ClassMethods#get_hook) @return (see ClassMethods#get_hook) @since (see ClassMethods#get_hook) @api (see ClassMethods#get_hook)

# File lib/public_activity/common.rb, line 172
def get_hook(key)
  self.class.get_hook(key)
end
prepare_custom_fields(options) click to toggle source

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

# 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 = {}) click to toggle source

Helper method to serialize class name into relevant key @return [String] the resulted key @param [Symbol] or [String] the name of the operation to be done on class @param [Hash] options to be used on key generation, defaults to {}

# 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) click to toggle source

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

# 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) click to toggle source

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

# 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(*args) click to toggle source

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

@see create_activity @return [Hash] Settings with preserved options that were passed @api private @overload prepare_settings(action, options = {})

@see #create_activity

@overload prepare_settings(options = {})

@see #create_activity
# 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?() click to toggle source

Returns true if PublicActivity is enabled globally and for this class. @return [Boolean] @api private @since 0.5.0

# File lib/public_activity/common.rb, line 163
def public_activity_enabled?
  PublicActivity.enabled?
end
reset_activity_instance_options() click to toggle source

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. @private

# 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