conscript 0.0.2 → 0.1.0

data/README.md

@@ -95,6 +95,18 @@ A list of options are below:
 
 - `:associations` an array of `has_many` association names to duplicate. These will be copied to the draft and overwrite the original instance's when published. Deep cloning is possible thanks to the [`deep_cloneable`](https://github.com/moiristo/deep_cloneable) gem. Refer to the `deep_cloneable` documentation to get an idea of how far you can go with this. Please note: `belongs_to` associations aren't supported as these should be drafted separately.
 - `:ignore_attributes` an array of attribute names which should _not_ be duplicated. Timestamps and STI `type` columns are excluded by default. Don't include association names here.
+- `:allow_update_with_drafts` (`false`) whether to allow an instance to be updated if it has draft instances
+- `:destroy_drafts_on_publish` (`true`) whether to destroy all other drafts for an instance when publishing a draft
+
+
+### Callbacks
+
+Two extra callbacks are made available for you to wrap bespoke behaviour around the draft lifecycle:
+
+- `save_as_draft`
+- `publish_draft`
+
+You can call `set_callback` with `:before`, `:after` or `:around` as normal.
 
 
 ### Using with CarrierWave
@@ -116,13 +128,17 @@ This will result in uploads for drafts being stored in the same location as the
 Conscript also overrides CarrierWave's `#destroy` callbacks to ensure that no other instance is using the same file before deleting it from the filesystem. Otherwise this can happen when you delete a draft with the same file as the original instance.
 
 
-### Limitations
+### Gotchas
+
+If saving drafts of models with `has_many` associations, the associated model should define a reciprocal `belongs_to` relationship (as normal). However, if it also has a presence validation e.g. `validates parent_model_name, presence: true` then you will encounter a limitation of ActiveRecord's default scopes. To avoid this when saving drafts with associations, wrap your save code with a `Model.unscoped` block, e.g:
+
+    Article.unscoped { draft = article.save_as_draft! }
 
-For reasons of sanity:
+Or if updating an existing draft:
 
-- You cannot make changes to an instance if it has drafts, this is because it would be difficult to propogate those changes down or provide visibility of the changes.
-- When you publish a draft, any other drafts for the same `draft_parent` are also destroyed.
+    Article.unscoped { draft.save! }
 
+Otherwise you'll encounter a validation error.
 
 ## Contributing
 

data/lib/conscript/orm/activerecord.rb

@@ -10,20 +10,26 @@ module Conscript
       cattr_accessor :conscript_options, :instance_accessor => false do
         {
           associations: [],
-          ignore_attributes: [self.primary_key, 'type', 'created_at', 'updated_at', 'draft_parent_id', 'is_draft']
+          ignore_attributes: [self.primary_key, 'type', 'created_at', 'updated_at', 'draft_parent_id', 'is_draft'],
+          allow_update_with_drafts: false,
+          destroy_drafts_on_publish: true
         }
       end
 
-      self.conscript_options.each_pair {|key, value| self.conscript_options[key] = Array(value) | Array(options[key]) }
+      self.conscript_options.slice(:associations, :ignore_attributes).each_pair {|key, value| self.conscript_options[key] = Array(value) | Array(options[key]) }
       self.conscript_options[:associations].map!(&:to_sym)
       self.conscript_options[:ignore_attributes].map!(&:to_s)
+      self.conscript_options.update options.slice(:allow_update_with_drafts, :destroy_drafts_on_publish)
 
       default_scope { where(is_draft: false) }
 
       belongs_to :draft_parent, class_name: self
       has_many :drafts, conditions: {is_draft: true}, class_name: self, foreign_key: :draft_parent_id, dependent: :destroy, inverse_of: :draft_parent
 
-      before_save :check_no_drafts_exist
+      define_callbacks :publish_draft, :save_as_draft
+
+      before_save :check_no_drafts_exist if (self.conscript_options[:allow_update_with_drafts] == false)
+      set_callback :publish_draft, :before, :destroy_all_drafts if (self.conscript_options[:destroy_drafts_on_publish] == true)
 
       # Prevent deleting CarrierWave uploads which may be used by other instances. Uploaders must be mounted beforehand.
       if self.respond_to? :uploaders
@@ -37,31 +43,34 @@ module Conscript
         end
 
         def save_as_draft!
-          raise Conscript::Exception::AlreadyDraft if is_draft?
-          draft = new_record? ? self : dup(include: self.class.conscript_options[:associations])
-          draft.is_draft = true
-          draft.draft_parent = self unless new_record?
-          self.class.base_class.unscoped { draft.save! }
-          draft
+          run_callbacks :save_as_draft do
+            raise Conscript::Exception::AlreadyDraft if is_draft?
+            draft = new_record? ? self : dup(include: self.class.conscript_options[:associations])
+            draft.is_draft = true
+            draft.draft_parent = self unless new_record?
+            self.class.base_class.unscoped { draft.save! }
+            draft
+          end
         end
 
         def publish_draft
-          raise Conscript::Exception::NotADraft unless is_draft?
-          return self.update_attribute(:is_draft, false) if !draft_parent_id
-          ::ActiveRecord::Base.transaction do
-            draft_parent.assign_attributes attributes_to_publish, without_protection: true
-
-            self.class.conscript_options[:associations].each do |association|
-              case reflections[association].macro
-                when :has_many
-                  draft_parent.send(association.to_s + "=", self.send(association).collect {|child| child.dup })
+          run_callbacks :publish_draft do
+            raise Conscript::Exception::NotADraft unless is_draft?
+            return self.update_attribute(:is_draft, false) if !draft_parent_id
+            ::ActiveRecord::Base.transaction do
+              draft_parent.assign_attributes attributes_to_publish, without_protection: true
+
+              self.class.conscript_options[:associations].each do |association|
+                case reflections[association].macro
+                  when :has_many
+                    draft_parent.send(association.to_s + "=", self.send(association).collect {|child| child.dup })
+                end
               end
-            end
 
-            draft_parent.drafts.destroy_all
-            draft_parent.save!
+              draft_parent.save!
+            end
+            draft_parent
           end
-          draft_parent
         end
 
         def uploader_store_param
@@ -85,6 +94,10 @@ module Conscript
               self.send("remove_" + attribute.to_s + "!") if !draft_parent_id or draft_parent.drafts.where(attribute => filename).count == 0
             end
           end
+
+          def destroy_all_drafts
+            draft_parent.drafts.destroy_all if draft_parent_id
+          end
       RUBY
     end
   end

data/lib/conscript/version.rb

@@ -1,3 +1,3 @@
 module Conscript
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

data/spec/conscript/orm/activerecord_spec.rb

@@ -31,10 +31,46 @@ describe Conscript::ActiveRecord do
       Widget.register_for_draft
     end
 
-    it "accepts options and merges them with defaults" do
-      Widget.register_for_draft(associations: :owners, ignore_attributes: :custom_attribute)
-      Widget.conscript_options[:associations].should == [:owners]
-      Widget.conscript_options[:ignore_attributes].should == ["id", "type", "created_at", "updated_at", "draft_parent_id", "is_draft", "custom_attribute"]
+    describe "options" do
+      it "accepts options and merges them with defaults" do
+        Widget.register_for_draft(associations: :owners, ignore_attributes: :custom_attribute)
+        Widget.conscript_options[:associations].should == [:owners]
+        Widget.conscript_options[:ignore_attributes].should == ["id", "type", "created_at", "updated_at", "draft_parent_id", "is_draft", "custom_attribute"]
+      end
+
+      describe ":allow_update_with_drafts" do
+        context "when true" do
+          it "does not register #check_no_drafts_exist as a callback" do
+            Widget.should_not_receive(:before_save)
+            Widget.register_for_draft(allow_update_with_drafts: true)
+          end
+        end
+
+        context "when false" do
+          it "registers #check_no_drafts_exist as a callback on before_save" do
+            Widget.should_receive(:before_save).once.with(:check_no_drafts_exist)
+            Widget.register_for_draft(allow_update_with_drafts: false)
+          end
+        end
+      end
+
+      describe ":destroy_drafts_on_publish" do
+        context "when true" do
+          it "registers #destroy_all_drafts as a before callback on publish_draft" do
+            Widget.register_for_draft(destroy_drafts_on_publish: true)
+            callback = Widget._publish_draft_callbacks.first
+            callback.filter.should == :destroy_all_drafts
+            callback.kind.should == :before
+          end
+        end
+
+        context "when false" do
+          it "does not register #destroy_all_drafts as a callback" do
+            Widget.register_for_draft(destroy_drafts_on_publish: false)
+            Widget._publish_draft_callbacks.should be_empty
+          end
+        end
+      end
     end
 
     describe "CarrierWave compatibility" do
@@ -98,6 +134,17 @@ describe Conscript::ActiveRecord do
     end
   end
 
+  describe "#destroy_all_drafts" do
+    context "with a draft_parent" do
+      it "destroys all drafts" do
+        @original = Widget.create
+        @draft = @original.save_as_draft!
+        @original.stub_chain(:drafts, :destroy_all).and_return('test')
+        @draft.send(:destroy_all_drafts).should == 'test'
+      end
+    end
+  end
+
   describe "#clean_uploaded_files_for_draft!" do
     before do
       Widget.cattr_accessor :uploaders
@@ -270,13 +317,6 @@ describe Conscript::ActiveRecord do
           -> { @duplicate.reload }.should raise_error(ActiveRecord::RecordNotFound)
         end
 
-        it "destroys the parent's other drafts" do
-          3.times { @original.save_as_draft! }
-          @original.drafts.count.should == 4
-          @duplicate.publish_draft
-          @original.drafts.count.should == 0
-        end
-
         context "where attributes were excluded in register_for_draft" do
           before { Widget.register_for_draft ignore_attributes: :name }
 
@@ -350,4 +390,34 @@ describe Conscript::ActiveRecord do
       end
     end
   end
+
+  describe "callbacks" do
+    describe "publish_draft" do
+      it "is defined" do
+        Widget.register_for_draft
+        Widget._publish_draft_callbacks.should_not == nil
+      end
+
+      it "can be set" do
+        Widget.any_instance.should_receive(:test_callback).once
+        Widget.register_for_draft
+        Widget.set_callback :publish_draft, :before, :test_callback
+        Widget.create(is_draft: true).publish_draft
+      end
+    end
+
+    describe "save_as_draft" do
+      it "is defined" do
+        Widget.register_for_draft
+        Widget._save_as_draft_callbacks.should_not == nil
+      end
+
+      it "can be set" do
+        Widget.any_instance.should_receive(:test_callback).once
+        Widget.register_for_draft
+        Widget.set_callback :save_as_draft, :before, :test_callback
+        Widget.new.save_as_draft!
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: conscript
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2013-07-09 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70297027681520 !ruby/object:Gem::Requirement
+  requirement: &70155455728440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 1.3.5
   type: :development
   prerelease: false
-  version_requirements: *70297027681520
+  version_requirements: *70155455728440
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70297027681100 !ruby/object:Gem::Requirement
+  requirement: &70155455727800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70297027681100
+  version_requirements: *70155455727800
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70297027680500 !ruby/object:Gem::Requirement
+  requirement: &70155455727040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70297027680500
+  version_requirements: *70155455727040
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70297027679880 !ruby/object:Gem::Requirement
+  requirement: &70155455726620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70297027679880
+  version_requirements: *70155455726620
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &70297027679120 !ruby/object:Gem::Requirement
+  requirement: &70155455726120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 3.2.13
   type: :runtime
   prerelease: false
-  version_requirements: *70297027679120
+  version_requirements: *70155455726120
 - !ruby/object:Gem::Dependency
   name: deep_cloneable
-  requirement: &70297027675000 !ruby/object:Gem::Requirement
+  requirement: &70155455725600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,7 +76,7 @@ dependencies:
         version: 1.5.2
   type: :runtime
   prerelease: false
-  version_requirements: *70297027675000
+  version_requirements: *70155455725600
 description: Provides ActiveRecord models with draft instances, including associations
 email:
 - steve@stevelorek.com