seomoz-ripple 1.0.0.pre

data/lib/ripple/embedded_document.rb

@@ -0,0 +1,64 @@
+require 'active_support/concern'
+require 'active_support/core_ext/hash/except'
+require 'ripple/translation'
+require 'ripple/embedded_document/around_callbacks'
+require 'ripple/embedded_document/finders'
+require 'ripple/embedded_document/persistence'
+require 'ripple/properties'
+require 'ripple/attribute_methods'
+require 'ripple/timestamps'
+require 'ripple/validations'
+require 'ripple/associations'
+require 'ripple/callbacks'
+require 'ripple/conversion'
+require 'ripple/inspection'
+require 'ripple/nested_attributes'
+require 'ripple/serialization'
+
+module Ripple
+  # Represents a document model that is composed into or stored in a parent
+  # Document.  Embedded documents may also embed other documents, have
+  # callbacks and validations, but are solely dependent on the parent Document.
+  module EmbeddedDocument
+    extend ActiveSupport::Concern
+    include Translation
+
+    included do
+      extend ActiveModel::Naming
+      include Persistence
+      extend Ripple::Properties
+      include Ripple::AttributeMethods
+      include Ripple::Timestamps
+      include Ripple::Validations
+      include Ripple::Associations
+      include Ripple::Callbacks
+      include Ripple::EmbeddedDocument::AroundCallbacks
+      include Ripple::Conversion
+      include Finders
+      include Ripple::Inspection
+      include Ripple::NestedAttributes
+      include Ripple::Serialization
+    end
+
+    module ClassMethods
+      def embeddable?
+        true
+      end
+    end
+
+    module InstanceMethods
+      def ==(other)
+        self.class == other.class &&
+        _parent_document == other._parent_document &&
+        serializable_hash == other.serializable_hash
+      end
+      alias eql? ==
+
+      def hash
+        parent = [_parent_document.class]
+        parent << [_parent_document.key] if _parent_document.respond_to?(:key)
+        [ self.class, parent, serializable_hash ].hash
+      end
+    end
+  end
+end

data/lib/ripple/embedded_document/around_callbacks.rb

@@ -0,0 +1,18 @@
+require 'ripple/callbacks'
+
+module Ripple
+  module EmbeddedDocument
+    module AroundCallbacks
+      extend ActiveSupport::Concern
+      extend Translation
+
+      included do
+        Ripple::Callbacks::CALLBACK_TYPES.each do |type|
+          define_singleton_method "around_#{type}" do |*args|
+            raise NotImplementedError.new(t("around_callbacks_not_supported", :type => type))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ripple/embedded_document/finders.rb

@@ -0,0 +1,26 @@
+require 'active_support/concern'
+require 'active_support/inflector'
+
+module Ripple
+  module EmbeddedDocument
+    # @private
+    module Finders
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def instantiate(attrs)
+          begin
+            klass = attrs['_type'].present? ? attrs.delete('_type').constantize : self
+          rescue NameError
+            klass = self
+          end
+          klass.new.tap do |object|
+            object.raw_attributes = attrs
+            object.changed_attributes.clear
+          end
+        end
+      end
+      
+    end
+  end
+end

data/lib/ripple/embedded_document/persistence.rb

@@ -0,0 +1,77 @@
+require 'active_support/concern'
+require 'ripple/translation'
+
+module Ripple
+  # Exception raised when save is called on an EmbeddedDocument that
+  # is not attached to a root Document.
+  class NoRootDocument < StandardError
+    include Translation
+    def initialize(doc, method)
+      super(t("no_root_document", :doc => doc.inspect, :method => method))
+    end
+  end
+
+  module EmbeddedDocument
+    # Adds methods to {Ripple::EmbeddedDocument} that delegate storage
+    # operations to the parent document.
+    module Persistence
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Creates a method that points to the parent document. 
+        def embedded_in(parent)
+          define_method(parent) { @_parent_document }
+        end
+      end
+
+      module InstanceMethods
+        # The parent document to this embedded document. This may be a
+        # {Ripple::Document} or another {Ripple::EmbeddedDocument}.
+        attr_accessor :_parent_document
+
+        # Whether the root document is unsaved.
+        def new?
+          if _root_document
+            _root_document.new?
+          else
+            true
+          end
+        end
+
+        # Sets this embedded documents attributes and saves the root document.
+        def update_attributes(attrs)
+          self.attributes = attrs
+          save
+        end
+
+        # Updates this embedded document's attribute and saves the
+        # root document, skipping validations.
+        def update_attribute(attribute, value)
+          send("#{attribute}=", value)
+          save(:validate => false)
+        end
+
+        # Saves this embedded document by delegating to the root document.
+        def save(*args)
+          if _root_document
+            run_save_callbacks do
+              _root_document.save(*args)
+            end
+          else
+            raise NoRootDocument.new(self, :save)
+          end
+        end
+
+        # @private
+        def attributes_for_persistence
+          raw_attributes.merge("_type" => self.class.name)
+        end
+
+        # The root {Ripple::Document} to which this embedded document belongs.
+        def _root_document
+          @_parent_document.try(:_root_document)
+        end
+      end
+    end
+  end
+end

data/lib/ripple/i18n.rb

@@ -0,0 +1,2 @@
+require 'active_support/i18n'
+I18n.load_path << File.expand_path("../locale/en.yml", __FILE__)

data/lib/ripple/inspection.rb

@@ -0,0 +1,32 @@
+require 'ripple'
+
+module Ripple
+  # Makes IRB and other inspect output a bit friendlier
+  module Inspection
+
+    # A human-readable version of the {Ripple::Document} or {Ripple::EmbeddedDocument}
+    # plus attributes
+    def inspect
+      attribute_list = attributes_for_persistence.except("_type").map {|k,v| "#{k}=#{v.inspect}" }.join(' ')
+      inspection_string(attribute_list)
+    end
+
+    # A string representation of the {Ripple::Document} or {Ripple::EmbeddedDocument}
+    def to_s
+      inspection_string
+    end
+
+    private
+
+    def inspection_string(extra = nil)
+      body = self.class.name + persistance_identifier
+      body += " #{extra}" if extra
+      "<#{body}>"
+    end
+
+    def persistance_identifier
+      self.class.embeddable? ? "" : ":#{key || '[new]'}"
+    end
+
+  end
+end

data/lib/ripple/locale/en.yml

@@ -0,0 +1,21 @@
+en:
+  ripple:
+    around_callbacks_not_supported: "around_%{type} callbacks are not supported on embedded documents.  See https://github.com/seancribbs/ripple/issues/188 for more detail."
+    associated_document_error_summary: "for %{doc_type} %{doc_id}: %{errors}"
+    attribute_hash: "value of attributes must be a Hash"
+    conflict_handler_not_implemented: "No on_conflict handler has been implemented for %{document}"
+    document_invalid: "Validation failed: %{errors}"
+    document_not_found: 
+      no_key: "Couldn't find document without a key"
+      one_key: "Couldn't find document with key: %{key}"
+      many_keys: "Couldn't find documents with keys: %{keys}"
+    invalid_association_value: "Invalid value %{value} for association %{name} of type %{klass} on %{owner}"
+    many_association_validation_error: "are invalid (%{association_errors})"
+    many_key_association: "You cannot use a many association using :key"
+    missing_configuration: "You are missing your ripple configuration file that should be at %{file}"
+    no_root_document: "You cannot call %{method} on %{doc} without a root document"
+    one_association_validation_error: "is invalid (%{association_errors})"
+    property_type_mismatch: "Cannot cast %{value} into a %{class}"
+    undefined_property: "Undefined property :%{prop} for class '%{class}'"
+    unexpected_conflicts: "Conflict cannot be resolved for %{conflicts} (for %{document})"
+

data/lib/ripple/nested_attributes.rb

@@ -0,0 +1,265 @@
+require 'active_support/concern'
+require 'active_support/core_ext/class/inheritable_attributes'
+
+module Ripple
+  module NestedAttributes #:nodoc:
+    extend ActiveSupport::Concern
+
+    UNASSIGNABLE_KEYS = %w{ _destroy }
+    TRUE_VALUES = [ true, "true", 1, "1", "yes", "ok", "y" ]
+
+    included do
+      class_inheritable_accessor :nested_attributes_options, :instance_writer => false
+      self.nested_attributes_options = {}
+    end
+    
+    # = Nested Attributes
+    #
+    # This is similar to the `accepts_nested_attributes` functionality
+    # as found in AR.  This allows the use update attributes and create
+    # new child records through the parent.  It also allows the use of
+    # the `fields_for` form view helper, using a presenter pattern.
+    #
+    # To enable in the model, call the class method, using the same
+    # relationship as defined in the `one` or `many`.
+    #
+    #   class Shipment
+    #     include Ripple::Document
+    #     one :box
+    #     many :addresses
+    #     accepts_nested_attributes_for :box, :addresses
+    #   end
+    #
+    # == One
+    #
+    # Given this model:
+    #
+    #   class Shipment
+    #     include Ripple::Document
+    #     one :box
+    #     accepts_nested_attributes_for :box
+    #   end
+    #
+    # This allows creating a box child during creation:
+    #
+    #   shipment = Shipment.create(:box_attributes => { :shape => 'square' })
+    #   shipment.box.shape # => 'square'
+    #
+    # This also allows updating box attributes:
+    #
+    #   shipment.update_attributes(:box_attributes => { :key => 'xxx', :shape => 'triangle' })
+    #   shipment.box.shape # => 'triangle'
+    #
+    # == Many
+    #
+    # Given this model
+    #
+    #   class Manifest
+    #     include Ripple::Document
+    #     many :shipments
+    #     accepts_nested_attributes_for :shipments
+    #   end
+    #
+    # This allows creating several shipments during manifest creation:
+    #
+    #   manifest = Manifest.create(:shipments_attributes => [ { :reference => "foo1" }, { :reference => "foo2" } ])
+    #   manifest.shipments.size # => 2
+    #   manifest.shipments.first.reference # => foo1
+    #   manifest.shipments.second.reference # => foo2
+    #
+    # And updating shipment attributes:
+    #
+    #   manifest.update_attributes(:shipment_attributes => [ { :key => 'xxx', :reference => 'updated foo1' },
+    #                                                        { :key => 'yyy', :reference => 'updated foo2' } ])
+    #   manifest.shipments.first.reference # => updated foo1
+    #   manifest.shipments.second.reference # => updated foo2
+    # 
+    # NOTE: On many embedded, then entire collection of embedded documents is replaced, as there
+    # is no key to specifically update.
+    #
+    # Given
+    #
+    #   class Manifest
+    #     include Ripple::Documnet
+    #     many :signatures
+    #     accepts_nested_attributes_for :signatures
+    #   end
+    #
+    #   class Signature
+    #     include Ripple::EmbeddedDocument
+    #     property :esignature, String
+    #   end
+    #
+    # The assigning of attributes replaces existing:
+    #   
+    #   manifest = Manifest.create(:signature_attributes => [ { :esig => 'a00001' }, { :esig => 'b00001' } ]
+    #   manifest.signatures # => [<Signature esig="a00001">, <Signature esig="b00001">]
+    #
+    #   manifest.signature_attributes = [ { :esig => 'c00001' } ]
+    #   manifest.signatures # => [<Signature esig="c00001">]
+    #     
+    module ClassMethods
+    
+      def accepts_nested_attributes_for(*attr_names)
+        options = { :allow_destroy => false }
+        options.update(attr_names.extract_options!)
+        
+        attr_names.each do |association_name|
+          if association = self.associations[association_name]
+            nested_attributes_options[association_name.to_sym] = options
+         
+            class_eval %{
+              def #{association_name}_attributes=(attributes)
+                assign_nested_attributes_for_#{association.type}_association(:#{association_name}, attributes)
+              end
+
+              before_save :autosave_nested_attributes_for_#{association_name}
+              before_save :destroy_marked_for_destruction
+
+              private
+
+              def autosave_nested_attributes_for_#{association_name}
+                save_nested_attributes_for_#{association.type}_association(:#{association_name}) if self.autosave[:#{association_name}]
+              end
+            }, __FILE__, __LINE__
+          else
+            raise ArgumentError, "Association #{association_name} not found!"
+          end
+        end        
+      end
+    end
+
+    module InstanceMethods
+
+      protected
+
+      def autosave
+        @autosave_nested_attributes_for ||= {}
+      end
+
+      def marked_for_destruction
+        @marked_for_destruction ||= {}
+      end
+
+      private
+      
+      def save_nested_attributes_for_one_association(association_name)
+        send(association_name).save
+      end
+
+      def save_nested_attributes_for_many_association(association_name)
+        send(association_name).map(&:save)
+      end
+
+      def destroy_marked_for_destruction
+        self.marked_for_destruction.each_pair do |association_name, resources|
+          resources.map(&:destroy)
+          send(association_name).reload
+        end
+      end
+
+      def destroy_nested_many_association(association_name)
+        send(association_name).map(&:destroy)
+      end
+
+      def assign_nested_attributes_for_one_association(association_name, attributes)
+        association = self.class.associations[association_name]
+        if association.embedded?
+          assign_nested_attributes_for_one_embedded_association(association_name, attributes)
+        else
+          self.autosave[association_name] = true
+          assign_nested_attributes_for_one_linked_association(association_name, attributes)
+        end
+      end
+      
+      def assign_nested_attributes_for_one_embedded_association(association_name, attributes)
+        send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS))
+      end
+
+      def assign_nested_attributes_for_one_linked_association(association_name, attributes)
+        attributes = attributes.stringify_keys
+        options = nested_attributes_options[association_name]
+
+        if attributes[key_attr.to_s].blank? && !reject_new_record?(association_name, attributes)
+          send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS))
+        else
+          if ((existing_record = send(association_name)).key.to_s == attributes[key_attr.to_s].to_s)
+            assign_to_or_mark_for_destruction(existing_record, attributes, association_name, options[:allow_destroy])
+          else
+            raise ArgumentError, "Attempting to update a child that isn't already associated to the parent."
+          end
+        end
+      end
+
+      def assign_nested_attributes_for_many_association(association_name, attributes_collection)
+        unless attributes_collection.is_a?(Hash) || attributes_collection.is_a?(Array)
+          raise ArgumentError, "Hash or Array expected, got #{attributes_collection.class.name} (#{attributes_collection.inspect})"
+        end
+
+        if attributes_collection.is_a? Hash
+          attributes_collection = attributes_collection.sort_by { |index, _| index.to_i }.map { |_, attributes| attributes }
+        end
+
+        association = self.class.associations[association_name]
+        if association.embedded?
+          assign_nested_attributes_for_many_embedded_association(association_name, attributes_collection)
+        else
+          self.autosave[association_name] = true
+          assign_nested_attributes_for_many_linked_association(association_name, attributes_collection)
+        end
+      end
+
+      def assign_nested_attributes_for_many_embedded_association(association_name, attributes_collection)
+        options = nested_attributes_options[association_name]
+        send(:"#{association_name}=", []) # Clobber existing
+        attributes_collection.each do |attributes|
+          attributes = attributes.stringify_keys
+          if !reject_new_record?(association_name, attributes)
+            send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS))
+          end
+        end
+      end
+
+      def assign_nested_attributes_for_many_linked_association(association_name, attributes_collection)
+        options = nested_attributes_options[association_name]
+        attributes_collection.each do |attributes|
+          attributes = attributes.stringify_keys
+
+          if attributes[key_attr.to_s].blank? && !reject_new_record?(association_name, attributes)
+            send(association_name).build(attributes.except(*UNASSIGNABLE_KEYS))
+          elsif existing_record = send(association_name).detect { |record| record.key.to_s == attributes[key_attr.to_s].to_s }
+            assign_to_or_mark_for_destruction(existing_record, attributes, association_name, options[:allow_destroy])
+          end
+        end
+      end
+    end
+
+    def assign_to_or_mark_for_destruction(record, attributes, association_name, allow_destroy)
+      if has_destroy_flag?(attributes) && allow_destroy
+        (self.marked_for_destruction[association_name] ||= []) << record
+      else
+        record.attributes = attributes.except(*UNASSIGNABLE_KEYS)
+      end
+    end
+    
+    def has_destroy_flag?(hash)
+      TRUE_VALUES.include?(hash.stringify_keys['_destroy'])
+    end
+
+    def reject_new_record?(association_name, attributes)
+      has_destroy_flag?(attributes) || call_reject_if(association_name, attributes)
+    end
+
+    def call_reject_if(association_name, attributes)
+      attributes = attributes.stringify_keys
+      case callback = nested_attributes_options[association_name][:reject_if]
+      when Symbol
+        method(callback).arity == 0 ? send(callback) : send(callback, attributes)
+      when Proc
+        callback.call(attributes)
+      end
+    end
+
+  end
+  
+end