lukewendling-expressive_record 0.1.0 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,7 @@
 2008-11-17 - 0.1.0
 ==========
-init release. still working out the bugs.
+init release. still working out the bugs.
+
+2008-11-17 - 0.2.0
+==========
+ready to play.

data/README.rdoc

@@ -1,27 +1,34 @@
 == Expressive Record
 
-Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes (http://dev.rubyonrails.org/changeset/9127)
+Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes (http://dev.rubyonrails.org/changeset/9127) to help with rolling your own history/audit logger.
 
 == Install
 
-sudo gem install lukewendling-expressive_record --source http://gems.github.com
+  script/plugin install git://github.com/lukewendling/expressive_record.git
+or
+  sudo gem install lukewendling-expressive_record --source http://gems.github.com
+
+create a migration for the audit table (see USAGE)
 
 == Usage
 
 ActiveRecord 2.1 introduces dirty changes; the ability to query a model object to track attribute changes before the record is saved using #changes, #changed, etc.
 
-However, belongs_to associations are cached simply as foreign key changes, so Ticket#changes yields something like ["status_id" => {"111", "222"}], which isn't especially helpful when rolling your own ticket history mechanism.
+However, belongs_to associations are cached simply as foreign key changes, so Ticket#changes yields something like {"status_id" => ["111", "222"]}, which isn't especially helpful when rolling your own audit logger.
 
-Expressive Records turns foreign key-based changes into meaningful terms.
+Expressive Record turns association (foreign key) changes into meaningful terms when the changes are saved to your audit table.
 
   class Ticket < ActiveRecord::Base
-    include ExpressRecord
+    include ExpressiveRecord
+    
+    has_many :ticket_changes
     
-    expressify_changes
+    # pass in the name of your audit table (optional)
+    express_changes :ticket_changes
     
   end
   
-expressify_changes uses a before_update callback to register changes in a separate log table, by convention, that has the following schema:
+express_changes adds a before_update callback to your model that inserts changes into an audit table with the following schema:
 
   class CreateTicketChanges < ActiveRecord::Migration
     def self.up
@@ -33,4 +40,10 @@ expressify_changes uses a before_update callback to register changes in a separa
         t.timestamps
       end
     end
-  end
+  end
+  
+== Limitations
+* the current implementation assumes that all belongs_to foreign keys use Rails conventional names, like user_id or status_id. if you are connecting to a legacy db with fk's like customerID or whatever, this won't work.
+
+== TODO
+* add migration generator to create conventionally-named log table (i.e. ticket_changes) to schema

data/Rakefile

@@ -2,8 +2,8 @@ require 'rubygems'
 require 'rake'
 require 'echoe'
 
-Echoe.new('expressive_record', '0.1.0') do |p|
-  p.description    = "Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes"
+Echoe.new('expressive_record', '0.2.0') do |p|
+  p.description    = "Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes to help with rolling your own history/audit logger."
   p.url			       = "http://github.com/lukewendling/expressive_record"
   p.author          = "Luke Wendling"
   p.email           = "luke@lukewendling.com"

data/expressive_record.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{expressive_record}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Luke Wendling"]
-  s.date = %q{2008-11-17}
-  s.description = %q{Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes}
+  s.date = %q{2008-11-18}
+  s.description = %q{Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes to help with rolling your own history/audit logger.}
   s.email = %q{luke@lukewendling.com}
   s.extra_rdoc_files = ["CHANGELOG", "lib/expressive_record.rb", "README.rdoc"]
   s.files = ["CHANGELOG", "expressive_record.gemspec", "init.rb", "lib/expressive_record.rb", "Manifest", "Rakefile", "README.rdoc"]
@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{expressive_record}
   s.rubygems_version = %q{1.3.1}
-  s.summary = %q{Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes}
+  s.summary = %q{Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes to help with rolling your own history/audit logger.}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION

data/lib/expressive_record.rb

@@ -2,12 +2,15 @@ module ExpressiveRecord
   def self.included(base)
     base.extend ClassMethods
   end
-  
-  def express_changes
+
+  # convention: the has_many association is named, i.e. ticket_changes, for model Ticket
+  def expressify(has_many_assoc = nil)
     ActiveRecord::Base.transaction do
       self.changes.each do |attr, values|
         valuefied = valuefy(attr, values)
-        ticket_changes.create(:attribute_type => attr, :old_value => valuefied[0], :new_value => valuefied[1])
+        assoc_name = has_many_assoc || "#{self.class.to_s.downcase}_changes"
+        assoc = self.send(assoc_name.to_sym)
+        assoc.create(:attribute_type => attr, :old_value => valuefied[0], :new_value => valuefied[1])
       end
     end
   end
@@ -25,9 +28,10 @@ module ExpressiveRecord
     end
 
   module ClassMethods
-    def expressify_changes
+    def express_changes(has_many_assoc = nil)
       before_update do |record|
-        record.express_changes
+        record.expressify has_many_assoc
       end
     end
-  end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: lukewendling-expressive_record
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Luke Wendling
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-11-17 00:00:00 -08:00
+date: 2008-11-18 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
-description: Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes
+description: Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes to help with rolling your own history/audit logger.
 email: luke@lukewendling.com
 executables: []
 
@@ -61,6 +61,6 @@ rubyforge_project: expressive_record
 rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
-summary: Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes
+summary: Add meaningful names for belongs_to associations to Rails 2.1 model object dirty changes to help with rolling your own history/audit logger.
 test_files: []