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


158
159
160
161
162
# File 'lib/public_activity/roles/tracked.rb', line 158

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


144
145
146
147
148
149
150
# File 'lib/public_activity/roles/tracked.rb', line 144

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

#assign_hooks(options) ⇒ Object


152
153
154
155
156
# File 'lib/public_activity/roles/tracked.rb', line 152

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_optionsObject


140
141
142
# File 'lib/public_activity/roles/tracked.rb', line 140

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

#include_default_actions(options) ⇒ Object


116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
# File 'lib/public_activity/roles/tracked.rb', line 116

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. [:parameters] 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 :parameters => { :title => :title, :author_name => "Michael", :category_name => proc {|controller, model_instance| model_instance.category.name}, :summary => proc {|controller, model_instance| truncate(model_instance.text, :length => 30)} } end

Values in the :parameters 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 => => 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.


104
105
106
107
108
109
110
111
112
113
114
# File 'lib/public_activity/roles/tracked.rb', line 104

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

  include_default_actions(options)

  assign_globals       options
  assign_hooks         options
  assign_custom_fields options

  nil
end