track_changes

TrackChanges is a Rails engine to facilitate tracking changes made to your models.

Release Notes

Version 1.0 is a major change. This gem has been re-written from scratch as a Rails 3.0 engine. You will need to take additional steps to upgrade from versions prior to 1.0.

General Upgrade Notes:

  • You no longer need to include TrackChanges in your controllers.

  • Additional arguments such as :only, and :except are no longer accepted in controllers

  • Any model that specifies track_changes will always have an Audit created on updates.

  • The revert capability is no longer available. This feature may return in the future.

Specific Upgrade Instructions:

  • Update your Gemfile

  • Remove all occurences of include TrackChanges from your controllers

  • Remove your existing Audit class in RAILS_ROOT/app/models, this class is now part of the engine

  • Modify any calls to track_changes to remove additional arguments

  • Modify your RAILS_ROOT/config/track_changes_configuration to the following:

    # Use whatever call you need to find the default user to be used if
# current_user is not set in your controller.
TrackChanges::Configuration::DEFAULT_USER_FINDER = Proc.new {
  User.where(:login => "admin")
}

Why?

I originally looked at the available auditing solutions and it appeared that most of them were not thread-safe.

Requirements

  • Rails 3

  • A User model

Development Requirements

  • JRuby

  • Rails 3

Installation

Add to your Gemfile:

gem 'track_changes'

Then, you can run rails generate track_changes to create the migration file, the initializer, and copy the CSS stylesheet to your application.

Configuration

Currently, the only configuration available is in the initializer config/initializers/track_changes_configuration.rb. In this file, you can set a constant TrackChanges::Configuration::DEFAULT_USER_FINDER to a Proc that will return a User model when no current_user is specified.

Model Example

To enable tracking for your model, add the statement track_changes in your model definition.

Example:

class Post < ActiveRecord::Base
  track_changes
end

This will add a polymorphic has_many association to the Audit class. It will also add an accessor current_user which you can set prior to updating your model. This will be saved in the Audit entry.

Controller Example

To enable automatic user tracking in your controllers. Add the track_changes statement to your controller. Pass a Symbol as an argument which is the name of the instance variable(s) (without the @). Theses instance variables will have their current_user attribute assigned to via the controller’s current_user method.

The track_changes method in your controller will also pull in the AuditsHelper module which provides some simple helpers.

Example:

In this example, after the ‘update` action is called, the `@post` will be compared to a previous version, and if there are any changes, an audit will be created.

class PostController < ApplicationController
  before_filter :get_post, :except => [:index, :new]
  # specify a single model
  track_changes :post
  # you can also specify multiple models
  #track_changes :post1, :post2, ...
  def update
    if @post.update_attributes(params[:post])
      flash[:notice] = "Success."
    else
      render :action => "edit"
    end
  end
  # Normal controller actions
  # ...
  protected
  def get_post
    @post = Post.find(params[:id])
  end
end

Note, you must have a before_filter that assigns the model to the expected instance variable.

Copyright © 2008-2010 Matt Haley. See LICENSE for details.