Introducing Shadow, a Rails Plugin

Over the past few months, Patrick Crowley and I have been working on the complete rewrite of the popular Cinema Treasures community website. With the overall goal of bringing more social functions to the site, we needed a way to track changes the community makes to Theaters and related information. In essence, we needed "activity feed" functionality akin to Facebook and other social networks.

While it is relatively straightforward to store changes (versioning) of a particular model, it is less trivial to track what changed in each version and who changed it. This could technically be considered "auditing", but that's not a very exciting name. I decided to go with the name Shadow, alluding to capturing and storing the shadow of a record at any given state (including its associations).

For visual reference, the figure below shows how you might use Shadow to generate user activity feeds:

The model code to achieve the above functionality (in this case showing the User activity for a Project with Milestones), could be:

class Project < ActiveRecord::Base
  has_many :milestones

  shadow :attributes => [:address, :description], :associations => :milestones, :attach => :user
end

The shadow code is currently hosted at Github and is a Rails Plugin. I have plans to convert this into a Merb-compatible RubyGem as well. For more information on using Shadow and the current TODOs respectively, see shadow and TODO.

Also, if you are running Edge Rails, it is possible to install this plugin with the following command:

$ ./script/plugin install git://github.com/TheBreeze/shadow.git

Otherwise, you'll need to run the following command (remember to change to your Rails app root):

  $ cd /path/to/your/rails/app
  $ git clone --depth 1 git://github.com/TheBreeze/shadow.git "./vendor/plugins/shadow/"; rm -rf ./vendor/plugins/shadow/.git