= track_changes

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

== 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 <tt>rails generate track_changes</tt> 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
<tt>config/initializers/track_changes_configuration.rb</tt>. In this file, you
can set a constant TrackChanges::Configuration::DEFAULT_USER_FINDER to a Proc
that will return a User model when no <tt>current_user</tt> is specified.

== Model Example

To enable tracking for your model, add the statement <tt>track_changes</tt> in
your model definition.

Example:

  class Post < ActiveRecord::Base
    track_changes
  end

This will add a polymorphic <tt>has_many</tt> association to the Audit class. It
will also add an accessor <tt>current_user</tt> 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 <tt>track_changes</tt>
statement to your controller. Pass a Symbol as an argument which is the name
of the instance variable(s) (without the <tt>@</tt>). Theses instance variables
will have their <tt>current_user</tt> attribute assigned to via the controller's
<tt>current_user</tt> method.

The <tt>track_changes</tt> 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 <tt>before_filter</tt> that assigns the model to the expected
instance variable.

== COPYRIGHT

Copyright (c) 2008-2010 Matt Haley. See LICENSE for details.