secretary-rails 1.0.0.beta1 → 1.0.0.beta2

data/README.md

@@ -1,5 +1,7 @@
 # Secretary
 
+[![Build Status](https://circleci.com/gh/SCPR/secretary-rails.png?circle-token=f1fadff9935d408e019bf9599b68aaf7a406d13b)](https://circleci.com/gh/SCPR/secretary-rails)
+
 #### A note about the Gem name
 There is another gem called [`secretary`](http://rubygems.org/gems/secretary),
 which hasn't been updated since 2008 and is obsolete. This gem is called
@@ -25,7 +27,7 @@ foreign keys to the object, and a foreign key to the user who saved the object.
 * Rails 3.2+
 * SQLite
 * MySQL? (untested)
-* Postgres? (untested)
+* PostgreSQL? (untested)
 
 ### Dependencies
 * [`activerecord`](http://rubygems.org/gems/activerecord) >= 3.2.0
@@ -41,7 +43,7 @@ gem 'secretary-rails'
 ```
 
 Run the install command, which will create a migration to add the `versions`
-table, and then run it:
+table, and then run the migration:
 
 ```
 bundle exec rails generate secretary:install
@@ -92,6 +94,27 @@ changes, which will include the information about the author(s).
 
 You can also pass in multiple association names into `tracks_association`.
 
+### Dirty Associations
+Secretary provides Rails-style `dirty attributes` for associations.
+Given an association `has_many :pets`, the methods available are:
+
+* **pets_changed?**
+* **pets_were**
+
+Secretary also merges in the association changes into the standard Rails
+`changes` hash:
+
+```ruby
+person.pets.to_a # => []
+
+person.pets << Pet.new(name: "Spot")
+
+person.pets_changed? # => true
+person.changed?      # => true
+person.pets_were     # => []
+person.changes       # => { "pets" => [[], [{ "name" => "Spot" }]]}
+```
+
 ### Tracking Users
 A version has an association to a user object, which tells you who created that
 version. The logged user is an attribute on the object being changed, so you
@@ -142,43 +165,52 @@ Sometimes you have an attribute on your model that either isn't public
 (not in the form), or you just don't want to version. You can tell Secretary
 to ignore these attributes globally by setting
 `Secretary.config.ignore_attributes`. You can also ignore attributes on a
-per-model basis by using one of two methods:
+per-model basis by using one of two options:
+
+**NOTE** The attributes *must* be specified as Strings.
 
 ```ruby
 class Article < ActiveRecord::Base
-  has_secretary
+  # Inclusion
+  has_secretary on: ["headline", "body"]
+end
+```
 
-  # Included
-  self.versioned_attributes = ["headline", "body"]
+```ruby
+class Article < ActiveRecord::Base
+# Exclusion
+  has_secretary except: ["published_at", "is_editable"]
 end
 ```
 
+By default, the versioned attributes are: the model's column names, minus the
+globally configured `ignored_attributes`, minus any excluded attributes
+you have set.
+
+Using `tracks_association` adds those associations to the
+`versioned_attributes` array:
+
 ```ruby
 class Article < ActiveRecord::Base
-  has_secretary
+  has_secretary on: ["headline"]
 
-  # Excluded
-  self.unversioned_attributes = ["published_at", "is_editable"]
+  has_many :images
+  tracks_association :images
 end
-```
 
-By default, `versioned_attributes` is the model's column names, minus the
-globally configured `ignored_attributes`, minus any `unversioned_attributes`
-you have set. `tracks_association` adds those associations to the
-`versioned_attributes` array.
+Article.versioned_attributes # => ["headline", "images"]
+``` 
 
 
 ## Contributing
 Fork it and send a pull request!
 
 ### TODO
-* Rails 4.1+ support.
-* Test (officially) with MySQL and SQLite.
+* See [Issues](https://github.com/SCPR/secretary-rails/issues).
 * Associations are only tracked one-level deep, It would be nice to also
   track the changes of the association (i.e. recognize when an associated
   object was changed and show its changed, instead of just showing a whole
   new object).
-* Support for Rails 3.0 and 3.1.
 
 ### Running Tests
 This library uses [appraisal](https://github.com/thoughtbot/appraisal) to test

data/lib/generators/secretary/install_generator.rb

@@ -1,4 +1,4 @@
-require 'rails/generators'
+require 'rails/generators/base'
 
 module Secretary
   class InstallGenerator < Rails::Generators::Base

data/lib/secretary/dirty/collection_association.rb

@@ -0,0 +1,74 @@
+module Secretary
+  module Dirty
+    module CollectionAssociation
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        private
+
+        def add_dirty_collection_association_methods(name)
+          module_eval <<-EOE, __FILE__, __LINE__ + 1
+            def #{name}_were
+              @#{name}_were ||= collection_association_was("#{name}")
+            end
+
+            def #{name}_changed?
+              collection_association_changed?("#{name}")
+            end
+
+
+            private
+
+            def preload_#{name}(object)
+              #{name}_were
+            end
+
+            def check_for_#{name}_changes
+              check_for_collection_association_changes("#{name}")
+            end
+
+            def clear_dirty_#{name}
+              @#{name}_were = nil
+            end
+          EOE
+        end
+      end
+
+
+      private
+
+      # This has to be run in a before_save callback,
+      # because we can't rely on the after_add, etc. callbacks
+      # to fill in our custom changes. For example, setting
+      # `self.animals_attributes=` doesn't run these callbacks.
+      def check_for_collection_association_changes(name)
+        persisted   = self.send("#{name}_were")
+        current     = self.send(name).to_a.reject(&:marked_for_destruction?)
+
+        persisted_attributes  = persisted.map(&:versioned_attributes)
+        current_attributes    = current.map(&:versioned_attributes)
+
+        if persisted_attributes != current_attributes
+          ensure_custom_changes_for_collection_association(name, persisted)
+          self.custom_changes[name][1] = current_attributes
+        end
+      end
+
+      def collection_association_was(name)
+        self.persisted? ? self.class.find(self.id).send(name).to_a : []
+      end
+
+      def collection_association_changed?(name)
+        check_for_collection_association_changes(name)
+        self.custom_changes[name].present?
+      end
+
+      def ensure_custom_changes_for_collection_association(name, persisted=nil)
+        self.custom_changes[name] ||= [
+          (persisted || self.send("#{name}_were")).map(&:versioned_attributes),
+          Array.new
+        ]
+      end
+    end
+  end
+end

data/lib/secretary/dirty/singular_association.rb

@@ -0,0 +1,84 @@
+module Secretary
+  module Dirty
+    module SingularAssociation
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        private
+
+        def add_dirty_singular_association_methods(name)
+          module_eval <<-EOE, __FILE__, __LINE__ + 1
+            def #{name}_was
+              if defined?(@#{name}_was)
+                @#{name}_was
+              else
+                @#{name}_was = singular_association_was("#{name}")
+              end
+            end
+
+            def #{name}_changed?
+              singular_association_changed?("#{name}")
+            end
+
+            def #{name}=(value)
+              preload_#{name}
+              obj = super
+              check_for_#{name}_changes
+              obj
+            end
+
+            private
+
+            def preload_#{name}(object=nil)
+              #{name}_was
+            end
+
+            def check_for_#{name}_changes
+              check_for_singular_association_changes("#{name}")
+            end
+
+            def clear_dirty_#{name}
+              remove_instance_variable(:@#{name}_was)
+            end
+          EOE
+        end
+      end
+
+
+      private
+
+      # This has to be run in a before_save callback,
+      # because we can't rely on the after_add, etc. callbacks
+      # to fill in our custom changes. For example, setting
+      # `self.animals_attributes=` doesn't run these callbacks.
+      def check_for_singular_association_changes(name)
+        persisted   = self.send("#{name}_was")
+        current     = self.send(name)
+
+        persisted_attributes = persisted ? persisted.versioned_attributes : {}
+
+        current_attributes = if current && !current.marked_for_destruction?
+          current.versioned_attributes
+        else
+          {}
+        end
+
+        if persisted_attributes != current_attributes
+          self.custom_changes[name] = [
+            persisted_attributes,
+            current_attributes
+          ]
+        end
+      end
+
+      def singular_association_was(name)
+        self.persisted? ? self.class.find(self.id).send(name) : nil
+      end
+
+      def singular_association_changed?(name)
+        check_for_singular_association_changes(name)
+        self.custom_changes[name].present?
+      end
+    end
+  end
+end

data/lib/secretary/dirty.rb

@@ -0,0 +1,8 @@
+module Secretary
+  module Dirty
+    extend ActiveSupport::Autoload
+
+    autoload :CollectionAssociation
+    autoload :SingularAssociation
+  end
+end

data/lib/secretary/errors.rb

@@ -1,10 +1,26 @@
-class Secretary::NotVersionedError < StandardError
-  def initialize(klasses=nil)
-    @klasses = Array(klasses)
+module Secretary
+  class NotVersionedError < StandardError
+    def initialize(klass=nil)
+      @klass = klass
+    end
+
+    def message
+      "Can't track an association on an unversioned model " \
+      "(#{@klass}) Did you declare `has_secretary` first?"
+    end
   end
 
-  def message
-    "Can't track an association on an unversioned model " \
-    "(#{@klasses.join(", ")}) Did you declare `has_secretary` first?"
+
+  class NoAssociationError < StandardError
+    def initialize(name=nil, klass=nil)
+      @name   = name
+      @klass  = klass
+    end
+
+    def message
+      "There is no association named #{@name} for the class #{@klass}. " \
+      "Check that you've already declared the association before calling " \
+      "'tracks_association', and that you use symbols."
+    end
   end
 end

data/lib/secretary/gem_version.rb

@@ -1,3 +1,3 @@
 module Secretary
-  GEM_VERSION = "1.0.0.beta1"
+  GEM_VERSION = "1.0.0.beta2"
 end

data/lib/secretary/has_secretary.rb

@@ -3,16 +3,26 @@ module Secretary
     extend ActiveSupport::Concern
 
     module ClassMethods
-      # Check if a class is versioned
+      # (Boolean) Check if a class is versioned
+      # Story.has_secretary? # => true or false
       def has_secretary?
         !!@_has_secretary
       end
 
-      # Apply to any class that should be versioned
-      def has_secretary
+      # Declare that this class shoudl be versioned.
+      # 
+      # Options:
+      # * `on` : Array of Strings which specifies which attributes should be
+      #   versioned.
+      # * `except` : Array of Strings which specifies which attributes should
+      #   NOT be versioned.
+      def has_secretary(options={})
         @_has_secretary = true
         Secretary.versioned_models.push self.name
 
+        self.versioned_attributes   = options[:on]     if options[:on]
+        self.unversioned_attributes = options[:except] if options[:except]
+
         has_many :versions,
           :class_name   => "Secretary::Version",
           :as           => :versioned,

data/lib/secretary/tracks_association.rb

@@ -13,9 +13,9 @@ module Secretary
       #   has_secretary
       #
       #   has_many :bylines,
-      #     :as               => :content,
-      #     :class_name       => "ContentByline",
-      #     :dependent        => :destroy
+      #     :as           => :content,
+      #     :class_name   => "ContentByline",
+      #     :dependent    => :destroy
       #
       #   tracks_association :bylines
       #
@@ -50,96 +50,54 @@ module Secretary
           raise NotVersionedError, self.name
         end
 
-        self.versioned_attributes += associations.map(&:to_s)
-
-        include InstanceMethodsOnActivation
-
         associations.each do |name|
-          module_eval <<-EOE, __FILE__, __LINE__ + 1
-            def #{name}_were
-              @#{name}_were ||= association_was("#{name}")
-            end
+          reflection = self.reflect_on_association(name)
 
-            def #{name}_changed?
-              association_changed?("#{name}")
-            end
+          if !reflection
+            raise NoAssociationError, name, self.name
+          end
 
+          self.versioned_attributes << name.to_s
 
-            private
+          if reflection.collection?
+            include Dirty::CollectionAssociation
+            add_dirty_collection_association_methods(name)
 
-            def preload_#{name}_were(object)
-              #{name}_were
-            end
+            add_callback_methods(:before_add, reflection,
+              [:"preload_#{name}"])
 
-            def check_for_#{name}_changes
-              check_for_association_changes("#{name}")
-            end
+            add_callback_methods(:before_remove, reflection,
+              [:"preload_#{name}"])
 
-            def clear_dirty_#{name}
-              @#{name}_were = nil
+            if ActiveRecord::VERSION::STRING >= "4.1.0"
+              ActiveRecord::Associations::Builder::CollectionAssociation
+              .define_callbacks(self, reflection)
+            else
+              redefine_callback(:before_add, name, reflection)
+              redefine_callback(:before_remove, name, reflection)
             end
-          EOE
+          else
+            include Dirty::SingularAssociation
+            add_dirty_singular_association_methods(name)
+          end
 
           before_save :"check_for_#{name}_changes"
           after_commit :"clear_dirty_#{name}"
-
-          add_callback_methods("before_add_for_#{name}", [
-            :"preload_#{name}_were"
-          ])
-
-          add_callback_methods("before_remove_for_#{name}", [
-            :"preload_#{name}_were"
-          ])
-
-          add_callback_methods("after_add_for_#{name}", [])
-          add_callback_methods("after_remove_for_#{name}", [])
         end
       end
 
       private
 
-      def add_callback_methods(method_name, new_methods)
-        original  = send(method_name)
-        methods   = original + new_methods
-        send("#{method_name}=", methods)
-      end
-    end
-
-
-    module InstanceMethodsOnActivation
-      private
-
-      # This has to be run in a before_save callback,
-      # because we can't rely on the after_add, etc. callbacks
-      # to fill in our custom changes. For example, setting
-      # `self.animals_attributes=` doesn't run these callbacks.
-      def check_for_association_changes(name)
-        persisted   = self.send("#{name}_were")
-        current     = self.send(name).to_a.reject(&:marked_for_destruction?)
-
-        persisted_attributes  = persisted.map(&:versioned_attributes)
-        current_attributes    = current.map(&:versioned_attributes)
-
-        if persisted_attributes != current_attributes
-          ensure_custom_changes_for_association(name, persisted)
-          self.custom_changes[name][1] = current_attributes
-        end
-      end
-
-      def association_was(name)
-        self.persisted? ? self.class.find(self.id).send(name).to_a : []
-      end
-
-      def association_changed?(name)
-        check_for_association_changes(name)
-        self.custom_changes[name].present?
+      def add_callback_methods(callback_name, reflection, new_methods)
+        reflection.options[callback_name] ||= Array.new
+        reflection.options[callback_name] += new_methods
       end
 
-      def ensure_custom_changes_for_association(name, persisted=nil)
-        self.custom_changes[name] ||= [
-          (persisted || self.send("#{name}_were")).map(&:versioned_attributes),
-          Array.new
-        ]
+      # Necessary for Rails < 4.1
+      def redefine_callback(callback_name, name, reflection)
+        send("#{callback_name}_for_#{name}=",
+          Array(reflection.options[callback_name])
+        )
       end
     end
   end

data/lib/secretary/versioned_attributes.rb

@@ -16,9 +16,6 @@ module Secretary
         # you can set `unversioned_attributes` to tell Secretary
         # which attributes to ignore.
         #
-        # Note: These should be set before any `tracks_association`
-        # macros are called.
-        #
         # Each takes an array of column names *as strings*.
         attr_writer :versioned_attributes
 

data/lib/secretary.rb

@@ -31,6 +31,7 @@ module Secretary
   autoload :HasSecretary
   autoload :VersionedAttributes
   autoload :TracksAssociation
+  autoload :Dirty
 end
 
 ActiveSupport.on_load(:active_record) do

data/spec/factories.rb

@@ -5,6 +5,17 @@ FactoryGirl.define do
     color "gray"
   end
 
+  factory :car do
+    name "Betsy"
+    color "white"
+    year 1984
+  end
+
+  factory :image do
+    title "Obama"
+    url "http://obama.com/obama.jpg"
+  end
+
   factory :location do
     title "Crawford Family Forum"
     address "474 S. Raymond, Pasadena"

data/spec/internal/app/models/animal.rb

@@ -1,7 +1,5 @@
 class Animal < ActiveRecord::Base
-  has_secretary
+  has_secretary on: ["name", "color"]
 
   belongs_to :person
-
-  self.versioned_attributes = ["name", "color"]
 end

data/spec/internal/app/models/car.rb

@@ -0,0 +1,2 @@
+class Car < ActiveRecord::Base
+end

data/spec/internal/app/models/image.rb

@@ -0,0 +1,6 @@
+class Image < ActiveRecord::Base
+  has_secretary on: ["title", "url"]
+
+  belongs_to :story
+  tracks_association :story
+end

data/spec/internal/app/models/person.rb

@@ -1,14 +1,10 @@
 class Person < ActiveRecord::Base
-  has_secretary
+  has_secretary except: ["name", "ethnicity"]
 
   belongs_to :location
-
   has_many :animals
-  accepts_nested_attributes_for :animals, allow_destroy: true
-
   has_many :hobbies
 
+  accepts_nested_attributes_for :animals, allow_destroy: true
   tracks_association :animals, :hobbies
-
-  self.unversioned_attributes = ["name", "ethnicity"]
 end

data/spec/internal/app/models/story.rb

@@ -1,3 +1,7 @@
 class Story < ActiveRecord::Base
   has_secretary
+
+  has_one :image
+  accepts_nested_attributes_for :image, allow_destroy: true
+  tracks_association :image
 end

data/spec/internal/db/schema.rb

@@ -7,12 +7,26 @@ ActiveRecord::Schema.define do
     t.timestamps
   end
 
+  create_table "cars", force: true do |t|
+    t.string "name"
+    t.string "color"
+    t.integer "year"
+    t.timestamps
+  end
+
   create_table "hobbies", force: true do |t|
     t.string "title"
     t.integer "person_id"
     t.timestamps
   end
 
+  create_table "images", force: true do |t|
+    t.string "title"
+    t.string "url"
+    t.integer "story_id"
+    t.timestamps
+  end
+
   create_table "locations", force: true do |t|
     t.string "title"
     t.text "address"