Module: PublicActivity::Tracked::ClassMethods

Defined in:
lib/public_activity/roles/tracked.rb

Overview

Module with basic tracked method that enables tracking models.

Instance Method Summary collapse

Instance Method Details

#assign_custom_fields(options) ⇒ Object 


189
190
191
192
193
 
# File 'lib/public_activity/roles/tracked.rb', line 189

def assign_custom_fields(options)
  options.except(*available_options).each do |k, v|
    self.activity_custom_fields_global[k] = v
  end
end

#assign_globals(options) ⇒ Object 


175
176
177
178
179
180
181
 
# File 'lib/public_activity/roles/tracked.rb', line 175

def assign_globals(options)
  [:owner, :recipient, :params].each do |key|
    if options[key]
      self.send("activity_#{key}_global=".to_sym, options.delete(key))
    end
  end
end

#assign_hooks(options) ⇒ Object 


183
184
185
186
187
 
# File 'lib/public_activity/roles/tracked.rb', line 183

def assign_hooks(options)
  if options[:on].is_a?(Hash)
    self.activity_hooks = options[:on].select {|_, v| v.is_a? Proc}.symbolize_keys
  end
end

#available_options ⇒ Object 


171
172
173
 
# File 'lib/public_activity/roles/tracked.rb', line 171

def available_options
  [:skip_defaults, :only, :except, :on, :owner, :recipient, :params].freeze
end

#include_default_actions(options) ⇒ Object 


147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/public_activity/roles/tracked.rb', line 147

def include_default_actions(options)
  defaults = {
    create:  Creation,
    destroy: Destruction,
    update:  Update
  }

  if options[:skip_defaults] == true
    return
  end

  modules = if options[:except]
    defaults.except(*options[:except])
  elsif options[:only]
    defaults.slice(*options[:only])
  else
    defaults
  end

  modules.each do |key, value|
    include value
  end
end

#tracked(opts = {}) ⇒ nil

Adds required callbacks for creating and updating tracked models and adds activities relation for listing associated activities.

Parameters:

:owner

Specify the owner of the Activity (person responsible for the action). It can be a Proc, Symbol or an ActiveRecord object:

Examples:

tracked :owner => :author
tracked :owner => proc {|o| o.author}

Keep in mind that owner relation is polymorphic, so you can't just provide id number of the owner object.

:recipient

Specify the recipient of the Activity It can be a Proc, Symbol, or an ActiveRecord object

Examples:

tracked :recipient => :author
tracked :recipient => proc {|o| o.author}

Keep in mind that recipient relation is polymorphic, so you can't just provide id number of the owner object.

:params

Accepts a Hash with custom parameters you want to pass to i18n.translate method. It is later used in Renderable#text method.

Example:

class Article < ActiveRecord::Base
  include PublicActivity::Model
  tracked :params => {
      :title => :title,
      :author_name => "Michael",
      :category_name => proc {|controller, model_instance| model_instance.category.name},
      :summary => proc {|controller, model_instance| truncate(model.text, :length => 30)}
  }
end

Values in the :params hash can either be an exact value, a Proc/Lambda executed before saving the activity or a Symbol which is a an attribute or a method name executed on the tracked model's instance.

Everything specified here has a lower priority than parameters specified directly in PublicActivity::Tracked#activity method. So treat it as a place where you provide 'default' values or where you specify what data should be gathered for every activity. For more dynamic settings refer to Activity model documentation.

:skip_defaults

Disables recording of activities on create/update/destroy leaving that to programmer's choice. Check Common#create_activity for a guide on how to manually record activities.

:only

Accepts a symbol or an array of symbols, of which any combination of the three is accepted:

  • :create

  • :update

  • :destroy

Selecting one or more of these will make PublicActivity create activities automatically for the tracked model on selected actions.

Resulting activities will have have keys assigned to, respectively:

  • article.create

  • article.update

  • article.destroy

Since only three options are valid, see :except option for a shorter version

:except

Accepts a symbol or an array of symbols with values like in :only, above. Values provided will be subtracted from all default actions: (create, update, destroy).

So, passing create would track and automatically create activities on update and destroy actions, but not on the create action.

:on

Accepts a Hash with key being the action on which to execute value (proc) Currently supported only for CRUD actions which are enabled in :only or :except options on this method.

Key-value pairs in this option define callbacks that can decide whether to create an activity or not. Procs have two attributes for use: model and controller. If the proc returns true, the activity will be created, if not, then activity will not be saved.

Example:

# app/models/article.rb
tracked :on => {:update => proc {|model, controller| model.published? }}

In the example above, given a model Article with boolean column published. The activities with key article.update will only be created if the published status is set to true on that article.

Parameters:

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

    options

Returns:

  • (nil) —

    options


135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/public_activity/roles/tracked.rb', line 135

def tracked(opts = {})
  options = opts.clone

  include_default_actions(options)

  assign_globals       options
  assign_hooks         options
  assign_custom_fields options

  nil
end