Adam @ Bitscribe

schema

   create_table 'change_logs' do |t|
      t.column :record_type, :text, :null => false
      t.column :record_id, :int, :null => false
      t.column :verb, :text, :null => false
      t.column :created_at, :datetime, :null => false
      t.column :user_id, :int
   end

To use, just include the module in any record whose changes you want to track, like so:

class MyRecord < ActiveRecord::Base
   include ChangeLogger
   ...
end

Now try something like this at the console:

r = MyRecord.new
r.save!
r.change_logs

ChangeLog.find_recent.first.to_s
ChangeLog.find_recent.first.record

Not bad. Now, to display to your users, create this partial:

app/views/change_log/_changes.rhtml

<h3>Change Log</h3>
<table>
<tbody>
   <% record.change_logs.each do |log| %>
      <tr>
         <td><%=h log.user || "System" %></td>
         <td><%=h log.verb %></td>
         <td><%=h log.created_at.relative_time %></td>
      </tr>
   <% end %>
</tbody>
</table>

If you’ve got a dashboard view of some sort, render this partial on it:

app/views/change_log/_recent.rhtml

<table>
<tbody>
   <% ChangeLog.recent.each do |log| %>
      <tr>
         <td>
            <%=h log.user || "System" %> <%=h log.verb %> <%=
            link_to_record log.record %>
         </td>
         <td><%=h log.created_at.relative_time %></td>
      </tr>
   <% end %>
</tbody>
</table>

To store the user making the changes through the interface, you will need to set the change log user in your base controller class. If you have the standard before_filter :authorize type of setup, something like this should work:

class ApplicationController < ActionController::Base
   before_filter :authorize
   def authorize
      ...
      @user = ...
      ChangeLogger.user = @user
   end
end

The views shown above use on two extra helper methods. First, relative_time is part of Bitscribe’s standard plugin library. You can use the code below, or just remove “.relative_time” from the created_at display if you want to display a standard date.

class Time
   def relative_time(from_time=Time.now)
   from_time = from_time.to_time if from_time.respond_to?(:to_time)
   distance_in_minutes = (((self - from_time).abs)/60).round

   case distance_in_minutes
   when 0..1
      return (distance_in_minutes==0) ? 'just seconds ago' : '1 min ago'
      when 2..45        then "#{distance_in_minutes} mins ago"
      when 46..90       then '1 hr ago'
      when 90..1440     then "#{(distance_in_minutes.to_f / 60.0).round} hrs ago"
      when 1441..2880   then 'Yesterday'
      when 2881..8640   then "#{(distance_in_minutes / 1440).round} days ago"
      when 8641..10080  then '1 week ago'
      else
         strftime year == from_time.year ? '%b %d' : '%b %d, %Y'
      end
   end
end

Second, also optional, is a helper for creating a link to any record. You may need to do this on a per-class basis, but if you use a standard CRUD scheme (which I endeavor to do wherever possible), then this will be sufficient:

   def link_to_record(r)
      type = r.class.to_s.gsub(/([A-Z])/, " \\1")
      link_to "#{type} #{r}", :controller => r.class.to_s.underscore, :action => 'show', :id => r.id
   end

This also assumes that all of your records have to_s defined. If they don’t,
you could change this to use “#{r.id}” as a stopgap, though the display will
then be much less useful to your users.

Also, all of your records now have a log_change method that takes one
argument, a verb, for custom change logs. A common example might be closing
an invoice, something like:

class Invoice
   def close
      transaction do
         closed_on = Time.now
         save!
         log_change 'closed'
      end
   end
end

Yes, this will create two change log entries: “updated” and “closed”. One way around this might be a set_next_change_verb method which will override “updated”, but this doesn’t strike me as incredibly elegant. If you’ve got a good idea for this, leave a comment.

A couple of notes on what this doesn’t do. It doesn’t track what changed, only when and by who. I’ve worked on a few apps that track the name of every field that changed, including what the value was before the change and what it was afterward. Although there are times you need this level of detail, my experience has been that this approach is way more difficult to create and maintain, and leads to a massive explosion of mostly unused data in your database. Not to mention that it’s very difficult to find a way to display the audit data to the user in a way that isn’t overwhelming.

It also doesn’t track deletions, which I left out for two reasons. For one, enterprise apps very rarely allow deletes, but instead mark things inactive and remove them from view. This keeps all the data relations intact, and also keeps records of historic data around indefinitely. For example if a customer cancels their account, the app still needs to store all their billing data for the company’s tax purposes. So log_change(’deactivated’) would be in order.

The second reason is that deletions will break the (polymorphic) association on the change logs, making them unable to display. You could get around this by creating a text field on the change log to store the to_s of the record such that, even if change_log.record is nil, you can still print out the record’s name. (You’d probably only want to do this on destroy logs, rather than all the time, because the name of the record might have changed.) If you need this functionality it wouldn’t be too hard to add.

This entry was posted on Saturday, December 9th, 2006 at 4:12 pm and is filed under Ruby. You can follow any responses to this entry through the RSS 2.0 feed. Responses are currently closed, but you can trackback from your own site.