pjb3-version_fu 1.0

data/MIT-LICENSE

@@ -0,0 +1,24 @@
+== version_fu
+Copyright (c) 2008 Jordan McKible
+
+== acts_as_versioned
+Copyright (c) 2005 Rick Olson
+====================================================================
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do 
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
+SOFTWARE.

data/README.rdoc

@@ -0,0 +1,131 @@
+= version_fu
+
+version_fu is a ActveRecord versioning plugin that takes advantage of the new dirty attribute checking available in Rails 2.1. Previous solutions like Rick Olson's acts_as_versioned are no long compatible with Rails.
+
+
+== Installation
+
+  ./script/plugin install git://github.com/jmckible/version_fu.git
+
+
+== Usage
+
+Let's say I have a pages table:
+
+  class Page < ActiveRecord::Base
+    # attributes: id, type, title, body, created_at, updated_at, creator_id, author_id
+  end
+
+I want to track any changes made.  First step will be to make a new page_versions table:
+
+  class CreatePageVersions < ActiveRecord::Migration
+    def self.up
+      create_table :page_versions do |t|
+        t.integer :page_id, :version, :author_id
+        t.string  :title
+        t.text    :body
+        t.timestamps
+      end
+    end
+  
+    def self.down
+      drop_table :page_versions
+    end
+  end
+
+In this case, the author_id column represents the last person to edit the page.  We want to track this attribute with every version.  However, the creator_id is the person who created the page.  The will never change, so it's not part of the versioned table.
+
+To look at previous versions:
+
+  Page.first.versions
+  
+Which will give you all of the previous versions, which are Page::Version objects.  If you want a specific version:
+
+  Page.first.find_version(2)
+
+Which will give you the Page::Version object that represents the page as of version 2.  If you need a read-only Page object that reflects the state of the object at the given version:
+
+  Page.first.as_of_version(2) 
+
+If you need to revert to an older version of the object:
+
+  Page.first.revert
+
+Which reverts to the previous version, or:
+
+  Page.first.revert_to(2)
+
+Which reverts to a specific version.
+
+Don't forget to add a version column to your pages table.  Have it default to 1 just to be safe (although the plugin should account for this):
+
+  class AddVersionToPages < ActiveRecord::Migration
+    def self.up
+      add_column :pages, :version, :integer, :default=>1
+    end
+    def self.down
+      remove_column :pages, :version
+    end
+  end
+
+Of course if you're adding this plugin to a table with existing data, you'll probably want to instantiate some initial versions to start with.
+
+Alright, so now that the database tables are in place, we can fire up version_fu.  It's quite simple:
+
+  class Page < ActiveRecord::Base
+    version_fu
+  end
+
+Thats it.
+
+
+== Configuration
+
+You can pass a few configuration options if need be.  If you stick with the defaults above, you can skip all this.
+
+  class Page < ActiveRecord::Base
+    version_fu :class_name=>'Version', :foreign_key=>'page_id', :table_name=>'page_versions', :version_column=>'version'
+  end
+
+* :class_name - The name of the versioned class.  It will be a submodule of the versioning class - e.g. Page::Version
+
+* :foreign_key - The column in the versioned table associated with the versioning class
+
+* :table_name - The name of the versioned table
+
+* :version_column - The name of the version column
+
+
+== Extensions
+
+Now that you've got some versions, it would be nice to use ActiveRecord associations on it.  For example, Page.first.versions.latest.author wouldn't currently work because the Page::Version class doesn't know about the author method.  The version_fu call does all you to pass a block which is executed by the versioned class.  There is just one gotcha for associations:
+
+  class Page < ActiveRecord::Base
+    version_fu do
+      belongs_to :author, :class_name=>'::Author'
+    end
+  end
+
+Don't forget the class name, or you'll get a warning
+
+== When to Version
+
+By default a new version will be saved whenever a versioned column is changed.  However, you can control this at a more fine grained level.  Just override the create_new_version? method.  For example, let's say you only want to save a new version if both the page title and body changed.  Taking advantage of the dirty attribute methods, you could do something like this:
+
+  class Page < ActiveRecord::Base
+    version_fu do
+      belongs_to :author, :class_name=>'::Author'
+    end
+    def create_new_version?
+      title_changed? && body_changed?
+    end
+  end
+
+
+== Author
+
+* version_fu was created by Jordan McKible http://jordan.mckible.com
+
+* Available on GitHub at http://github.com/jmckible/version_fu/tree/master
+
+* acts_as_versioned by Rick Olson http://github.com/technoweenie/acts_as_versioned/tree/master

data/lib/version_fu.rb

@@ -0,0 +1,128 @@
+module VersionFu
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def version_fu(options={}, &block)
+      return if self.included_modules.include? VersionFu::InstanceMethods
+      __send__ :include, VersionFu::InstanceMethods
+
+      cattr_accessor :versioned_class_name, :versioned_foreign_key, :versioned_table_name, 
+                     :version_column, :versioned_columns
+
+      self.versioned_class_name         = options[:class_name]  || 'Version'
+      self.versioned_foreign_key        = options[:foreign_key] || self.to_s.foreign_key
+      self.versioned_table_name         = options[:table_name]  || "#{table_name_prefix}#{base_class.name.demodulize.underscore}_versions#{table_name_suffix}"
+      self.version_column               = options[:version_column]    || 'version'
+
+      # Setup versions association
+      class_eval do
+        has_many :versions, :class_name  => "#{self.to_s}::#{versioned_class_name}",
+                            :foreign_key => versioned_foreign_key,
+                            :dependent   => :destroy do
+          def latest
+            find :first, :order=>'version desc'
+          end                    
+        end
+
+        before_save :check_for_new_version
+      end
+      
+      # Versioned Model
+      const_set(versioned_class_name, Class.new(ActiveRecord::Base)).class_eval do
+        # find first version before the given version
+        def self.before(version)
+          find :first, :order => 'version desc',
+            :conditions => ["#{original_class.versioned_foreign_key} = ? and version < ?", version.send(original_class.versioned_foreign_key), version.version]
+        end
+
+        # find first version after the given version.
+        def self.after(version)
+          find :first, :order => 'version',
+            :conditions => ["#{original_class.versioned_foreign_key} = ? and version > ?", version.send(original_class.versioned_foreign_key), version.version]
+        end
+
+        def previous
+          self.class.before(self)
+        end
+
+        def next
+          self.class.after(self)
+        end
+      end
+
+      # Housekeeping on versioned class
+      versioned_class.cattr_accessor :original_class
+      versioned_class.original_class = self
+      versioned_class.set_table_name versioned_table_name
+      
+      # Version parent association
+      versioned_class.belongs_to self.to_s.demodulize.underscore.to_sym, 
+        :class_name  => "::#{self.to_s}", 
+        :foreign_key => versioned_foreign_key
+      
+      # Block extension
+      versioned_class.class_eval &block if block_given?
+      
+      # Finally setup which columns to version
+      self.versioned_columns =  versioned_class.new.attributes.keys - 
+        [versioned_class.primary_key, versioned_foreign_key, version_column, 'created_at', 'updated_at']
+    end
+    
+    def versioned_class
+      const_get versioned_class_name
+    end
+  end
+
+
+  module InstanceMethods
+    def find_version(number)
+      versions.find :first, :conditions=>{:version=>number}
+    end
+    
+    def check_for_new_version
+      instatiate_revision if create_new_version?
+      true # Never halt save
+    end
+    
+    # This the method to override if you want to have more control over when to version
+    def create_new_version?
+      # Any versioned column changed?
+      self.class.versioned_columns.detect {|a| __send__ "#{a}_changed?"}
+    end
+    
+    def instatiate_revision
+      new_version = versions.build
+      versioned_columns.each do |attribute|
+        new_version.__send__ "#{attribute}=", __send__(attribute)
+      end
+      version_number = new_record? ? 1 : version + 1
+      new_version.version = version_number
+      self.version = version_number
+    end
+    
+    def revert
+      revert_to(version-1) unless version == 1
+    end
+    
+    def revert_to(version)
+      revert_to_version = find_version(version)
+      versioned_columns.each do |a|
+        send("#{a}=", revert_to_version.send(a))
+      end  
+      save
+    end    
+    
+    def as_of_version(version)
+      v = find_version(version)
+      obj = self.class.new
+      (versioned_columns + [:version, :updated_at]).each do |a|
+        obj.send("#{a}=", v.send(a))
+      end
+      obj.id = id
+      obj.freeze      
+    end
+    
+  end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+ActiveRecord::Base.send(:include, VersionFu)

data/version_fu.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name = %q{version_fu}
+  s.version = "1.0"
+ 
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jordan McKible", "Paul Barry"]
+  s.date = %q{2008-09-12}
+  s.description = %q{Dirty ActiveRecord Versioning (update of acts_as_versioned)}
+  s.email = %q{mail (at) paulbarry (dot) com}
+  s.extra_rdoc_files = ["lib/version_fu.rb", "README.rdoc"]
+  s.files = ["version_fu.gemspec", "lib/version_fu.rb", "rails/init.rb", "README.rdoc", "MIT-LICENSE"]
+  s.has_rdoc = true
+  s.homepage = %q{http://tuples.us/2008/05/03/lazily-announcing-version_fu/}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Version Fu", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{version_du}
+  s.rubygems_version = %q{1.2.0}
+  s.summary = %q{Gem version of version_fu Rails plugin.}
+ 
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: pjb3-version_fu
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Jordan McKible
+- Paul Barry
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-09-12 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Dirty ActiveRecord Versioning (update of acts_as_versioned)
+email: mail (at) paulbarry (dot) com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- lib/version_fu.rb
+- README.rdoc
+files: 
+- version_fu.gemspec
+- lib/version_fu.rb
+- rails/init.rb
+- README.rdoc
+- MIT-LICENSE
+has_rdoc: true
+homepage: http://tuples.us/2008/05/03/lazily-announcing-version_fu/
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Version Fu
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: version_du
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Gem version of version_fu Rails plugin.
+test_files: []
+