Module: WiserTrails::TrailIt::ClassMethods

Defined in:
lib/wiser_trails/roles/trail_it.rb

Overview

Module with basic tracked method that enables tracking models.

Instance Method Summary collapse

Instance Method Details

#trail_it(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 WiserTrails::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 WiserTrails::TrailIt#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 WiserTrails 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



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/wiser_trails/roles/trail_it.rb', line 133

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

  all_options = [:create, :update, :destroy]

  if !options.has_key?(:skip_defaults) && !options[:only] && !options[:except]
    include Creation
    include Destruction
    include Update
  end
  options.delete(:skip_defaults)

  if options[:except]
    options[:only] = all_options - Array(options.delete(:except))
  end

  if options[:only]
    Array(options[:only]).each do |opt|
      if opt.eql?(:create)
        include Creation
      elsif opt.eql?(:destroy)
        include Destruction
      elsif opt.eql?(:update)
        include Update
      end
    end
    options.delete(:only)
  end

  if options[:owner]
    self.activity_owner_global = options.delete(:owner)
  end
  if options[:account]
    self. = options.delete(:account)
  end
  if options.has_key?(:on) and options[:on].is_a? Hash
    self.activity_hooks = options.delete(:on).select {|_, v| v.is_a? Proc}.symbolize_keys
  end

  options.each do |k, v|
    self.activity_custom_fields_global[k] = v
  end

  nil
end