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

- (Object) assign_custom_fields(options)



187
188
189
190
191
# File 'lib/public_activity/roles/tracked.rb', line 187

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

- (Object) assign_globals(options)



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

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

- (Object) assign_hooks(options)



181
182
183
184
185
# File 'lib/public_activity/roles/tracked.rb', line 181

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

- (Object) available_options



169
170
171
# File 'lib/public_activity/roles/tracked.rb', line 169

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

- (Object) include_default_actions(options)



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

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

- (nil) tracked(opts = {})

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.



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

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

  include_default_actions(options)

  assign_globals       options
  assign_hooks         options
  assign_custom_fields options

  nil
end