custom_fields 1.0.0.beta.25 → 1.1.0.rc1

data/README.textile

@@ -1,16 +1,59 @@
 h1. CustomFields
 
 Manage custom fields to a mongoid document or a collection. This module is one of the core features we implemented in our custom cms named Locomotive.
+Basically, its aim is to provide to editors a way to manage extra fields to a Mongoid document through for instance a web UI.
+
+The main goals:
+
+* offering a very secure way to add / edit / delete extra fields to a Mongoid document
+* scoping the modifications added to a Mongoid document so that other documents of the same class won't be updated.
 
 h2. Requirements
 
-ActiveSupport 3.0.7, MongoDB 1.6 and Mongoid 2.0.2
+ActiveSupport 3.1.1, MongoDB 2.0 and Mongoid 2.3.2
+
+h2. Examples
+
+h3. On a has_many relationship
+
+bc.. class Company
+  embeds_many :employees
+
+  custom_fields_for :employees
+end
+
+class Employee
+  field :name, String
+
+  embedded_in :company, :inverse_of => :employees
+end
+
+company = Company.new
+company.employees_custom_fields.build :label => 'His/her position', :_alias => 'position', :kind => 'string', :required => true
+
+company.save
+
+company.employees.build :name => 'Michael Scott', :position => 'Regional manager'
+
+another_company = Company.new
+employee = company.employees.build
+employee.position # returns a "not defined method" error
+
+h3. On the class itself
+
+bc.. class Company
+  custom_fields_for_itself
+end
 
+company = Company.new
+company.self_metadata_custom_fields.build :label => 'Shipping Address', :_alias => 'address', :kind => 'text'
 
-h2. Example
+company.save
 
-Coming soon but take a look of the tests to see what CustomFields is capable of.
+company.self_metadata.address = '700 S Laflin, 60607 Chicago'
 
+another_company = Company.new
+other_company.self_metadata.address # returns a "not defined method" error
 
 h2. Contact
 

data/lib/custom_fields/custom_fields_for.rb

@@ -12,175 +12,329 @@ module CustomFields
 
     module InstanceMethods
 
-      def custom_fields_for?(collection_name)
-        self.class.custom_fields_for?(collection_name)
+      # Determines if the relation is enhanced by the custom fields
+      #
+      # @example the Person class has somewhere in its code this: "custom_fields_for :addresses"
+      #   person.custom_fields_for?(:addresses)
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ true, false ] True if enhanced, false if not.
+      #
+      def custom_fields_for?(name)
+        self.class.custom_fields_for?(name)
       end
 
+      # Returns the class enhanced by the custom fields defined in the parent class.
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ Class ] The modified class.
+      #
+      def klass_with_custom_fields(name)
+        self.class.klass_with_custom_fields(name, self)
+      end
+
+      # Returns the ordered list of custom fields for a relation
+      #
+      # @example the Person class has somewhere in its code this: "custom_fields_for :addresses"
+      #   person.ordered_custom_fields(:addresses)
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ Collection ] The ordered list.
+      #
+      def ordered_custom_fields(name)
+        self.send(:"#{name}_custom_fields").sort { |a, b| (a.position || 0) <=> (b.position || 0) }
+      end
+
+      # Marks all the custom fields as persisted. Actually, this is a patch
+      # for mongoid since for the update, it runs the reset_persisted_children method after
+      # the callbacks unlike for the create.
+      # We assume that all the fields have been validated in a previous step
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def mark_custom_fields_as_persisted(name)
+        self.send(:"#{name}_custom_fields").each do |field|
+          field.instance_variable_set(:@new_record, false) unless field.persisted?
+        end
+      end
+
+      # Builds the class enhanced by the custom fields defined in the parent class.
+      # The new class inherits from the original one.
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      # @param [ Metadata ] metadata The relation's metadata.
+      #
+      # @return [ Class ] The modified class.
+      #
+      def build_klass_with_custom_fields(name, metadata)
+        custom_fields = self.ordered_custom_fields(name)
+
+        metadata.klass.to_klass_with_custom_fields(name, self, custom_fields)
+      end
+
+      # Marks the class enhanced by the custom fields as invalidated
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def mark_klass_with_custom_fields_as_invalidated(name)
+        self.send(:"invalidate_#{name}_klass_flag=", true)
+      end
+
+      # Reset the flag telling if the class enhanced by the custom fields is invalidated
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def reset_klass_with_custom_fields_invalidated_flag(name)
+        # puts "* reset_klass_with_custom_fields_invalidated_flag #{name}"
+        self.send(:"invalidate_#{name}_klass_flag=", false)
+      end
+
+      # Determines if the enhanced class has to be invalidated.
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ true, false ] True if enhanced, false if not.
+      #
+      def invalidate_klass_with_custom_fields?(name)
+        !!self.send(:"invalidate_#{name}_klass_flag")
+      end
+
+      # Destroy the class enhanced by the custom fields so that next time we need it,
+      # we have a fresh new one.
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def invalidate_klass_with_custom_fields(name)
+        self.class.invalidate_klass_with_custom_fields(name, self)
+      end
+
+      # Duplicates a metadata and assigns the enhanced class to it.
+      #
+      # @param [ Metadata ] metadata The relation's old metadata.
+      #
+      # @return [ Metadata ] The relation's new metadata
+      #
       def clone_metadata_for_custom_fields(metadata)
-        singular_name = metadata.name.to_s.singularize.gsub(/^_/, '')
+        # puts "-> clone_metadata_for_custom_fields #{metadata.name}"
 
-        klass = self.send(:"fetch_#{singular_name}_klass")
+        klass = self.build_klass_with_custom_fields(metadata.name, metadata)
 
-        # safer to do that because we are going to modify the metadata klass for next operations
+        # we do not want that other instances of the parent class have the same metadata
         metadata.clone.tap do |metadata|
           metadata.instance_variable_set(:@klass, klass)
         end
       end
 
-    end
+      # When the fields have been modified and before the object is saved,
+      # we bump the version.
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def bump_custom_fields_version(name)
+        if self.invalidate_klass_with_custom_fields?(name)
+          # puts "%%% bump_custom_fields_version #{name} #{self.send(:"#{name}_custom_fields_version").inspect}"
+          version = self.send(:"#{name}_custom_fields_version") || 0
+          self.send(:"#{name}_custom_fields_version=", version + 1)
+        end
+      end
 
-    # Enhance an embedded collection OR the instance itself (by passing self) by providing methods to manage custom fields.
-    #
-    # class Company
-    #
-    #   custom_fields_for :self
-    #
-    #   embeds_many :employees
-    #   custom_fields_for :employees
-    # end
-    #
-    # class Employee
-    #    embedded_in :company, :inverse_of => :employees
-    #    field :name, String
-    # end
-    #
-    # company.employee_custom_fields.build :label => 'His/her position', :_alias => 'position', :kind => 'string'
-    #
-    # company.employees.build :name => 'Michael Scott', :position => 'Regional manager'
-    #
-    #
-    # company.self_custom_fields.build :label => 'Shipping Address', :_alias => 'address', :kind => 'text'
-    #
-    # company.metadata.address = '700 S Laflin, 60607 Chicago'
-    #
-    # other_company.metadata.address # returns a "not defined method" error
-    #
-    module ClassMethods
+      # Increments by 1 the counter couting the number of added custom fields
+      # for a relation
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ Integer ] The new value of the counter
+      #
+      def bump_custom_fields_counter(name)
+        counter = self.send(:"#{name}_custom_fields_counter") || 0
+        self.send(:"#{name}_custom_fields_counter=", counter + 1)
+      end
+
+      # Builds a new relation so that the builder takes the last version of
+      # the enhanced class when creating new instances
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def rebuild_custom_fields_relation(name)
+        # metadata = self.clone_metadata_for_custom_fields(self.relations[name.to_s])
+
+        # puts "rebuild_custom_fields_relation #{name}"
 
-      def custom_fields_for?(collection_name)
-        self._custom_fields_for.include?(collection_name.to_s)
+        metadata = self.relations[name.to_s]
+        self.build(name, nil, metadata)
       end
 
-      def custom_fields_for(collection_name)
-        singular_name                   = collection_name.to_s.singularize
-        dynamic_custom_field_class_name = "#{self.name}#{singular_name.camelize}Field"
+    end
 
-        self.declare_embedded_in_definition_in_custom_field(collection_name)
+    module ClassMethods
 
-        # enhance the class itself
-        if (itself = %w(itself self).include?(collection_name.to_s))
-          collection_name, singular_name = '_metadata', 'metadata'
+      # Determines if the relation is enhanced by the custom fields
+      #
+      # @example the Person class has somewhere in its code this: "custom_fields_for :addresses"
+      #   Person.custom_fields_for?(:addresses)
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ true, false ] True if enhanced, false if not.
+      #
+      def custom_fields_for?(name)
+        self._custom_fields_for.include?(name.to_s)
+      end
 
-          class_eval <<-EOV
-            embeds_one :#{collection_name}, :class_name => '::CustomFields::Metadata'
+      # Enhance an embedded collection OR the instance itself (by passing self) by providing methods to manage custom fields.
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @example
+      #   class Company
+      #     embeds_many :employees
+      #     custom_fields_for :employees
+      #   end
+      #
+      #   class Employee
+      #     embedded_in :company, :inverse_of => :employees
+      #     field :name, String
+      #   end
+      #
+      #   company.employees_custom_fields.build :label => 'His/her position', :_alias => 'position', :kind => 'string'
+      #   company.employees.build :name => 'Michael Scott', :position => 'Regional manager'
+      #
+      def custom_fields_for(name)
+        self.declare_embedded_in_definition_in_custom_field(name)
+
+        # stores the relation name
+        self._custom_fields_for << name.to_s
+
+        self.extend_for_custom_fields(name)
+      end
 
-            def safe_#{singular_name}
-              self.#{collection_name} || self.build_#{collection_name}
-            end
-          EOV
+      # Enhances the class itself
+      #
+      # @example
+      #   class Company
+      #     custom_fields_for_itself
+      #   end
+      #
+      #   company.self_metadata_custom_fields.build :label => 'Shipping Address', :_alias => 'address', :kind => 'text'
+      #   company.self_metadata.address = '700 S Laflin, 60607 Chicago'
+      #   other_company.self_metadata.address # returns a "not defined method" error
+      #
+      def custom_fields_for_itself
+        self.embeds_one :self_metadata, :class_name => '::CustomFields::SelfMetadata'
+
+        class_eval do
+          def self_metadata_with_automatic_build
+            object = self_metadata_without_automatic_build
+            object || self.build_self_metadata
+          end
+          alias_method_chain :self_metadata, :automatic_build
         end
 
-        # record the collection_name
-        self._custom_fields_for << collection_name.to_s
+        self.custom_fields_for('self_metadata')
+      end
 
-        # common part
-        class_eval <<-EOV
-          field :#{singular_name}_custom_fields_counter, :type => Integer, :default => 0
-          field :#{singular_name}_custom_fields_version, :type => Integer, :default => 0
-
-          embeds_many :#{singular_name}_custom_fields, :class_name => '#{dynamic_custom_field_class_name}' do
-            def build(attributes = {}, type = nil, &block)
-              instantiated(type).tap do |doc|
-                append(doc, default_options(:binding => true))
-                doc.write_attributes(attributes)
-                doc.identify
-                block.call(doc) if block
-              end
-            end
-            alias :new :build
-          end
+      protected
 
-          attr_accessor :invalidate_#{singular_name}_klass_flag
+      # Extends / Decorates the current class in order to be fully custom_fields compliant.
+      # it declares news fields, adds new callbacks, ...etc
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      def extend_for_custom_fields(name)
+        class_eval do
+          field :"#{name}_custom_fields_counter", :type => Integer, :default => 0
+          field :"#{name}_custom_fields_version", :type => Integer, :default => 0
 
-          before_save do |record|
-            if record.invalidate_#{singular_name}_klass?
-              record.#{singular_name}_custom_fields_version ||= 0
-              record.#{singular_name}_custom_fields_version += 1
-              # puts "[parent/before_save] set #{singular_name}_custom_fields_version " + record.#{singular_name}_custom_fields_version.to_s # debug purpose
-            end
-          end
+          embeds_many :"#{name}_custom_fields", :class_name => self.dynamic_custom_field_class_name(name), :cascade_callbacks => true
 
-          after_destroy     :invalidate_#{singular_name}_klass
+          attr_accessor :"invalidate_#{name}_klass_flag" # flag for invalidating the custom class
 
-          accepts_nested_attributes_for :#{singular_name}_custom_fields, :allow_destroy => true
+          accepts_nested_attributes_for :"#{name}_custom_fields", :allow_destroy => true
+        end
 
-          def ordered_#{singular_name}_custom_fields
-            self.#{singular_name}_custom_fields.sort { |a, b| (a.position || 0) <=> (b.position || 0) }
-          end
+        class_eval <<-EOV
 
-          def fetch_#{singular_name}_klass
-            metadata = self.relations['#{collection_name.to_s}']
-            metadata.klass.to_klass_with_custom_fields(self.ordered_#{singular_name}_custom_fields, self, metadata.name)
-          end
+          before_save   :bump_#{name}_custom_fields_version
+          after_save    :mark_#{name}_custom_fields_as_persisted
+          after_save    :rebuild_#{name}_relation
+          after_save    :reset_#{name}_klass_invalidated_flag
+          after_destroy :invalidate_#{name}_klass
 
-          def #{singular_name}_klass
-            metadata = self.relations['#{collection_name.to_s}']
-            metadata.klass.current_klass_with_custom_fields(self, metadata.name)
+          def #{name}_klass
+            self.klass_with_custom_fields('#{name}')
           end
 
-          def #{singular_name}_klass_out_of_date?
-            self.#{singular_name}_klass.nil? || self.#{singular_name}_klass.version != self.#{singular_name}_custom_fields_version
+          def #{name}_klass_name
+            self.class.klass_name_with_custom_fields('#{name}', self)
           end
 
-          def invalidate_#{singular_name}_klass
-            metadata = self.relations['#{collection_name.to_s}']
-            metadata.klass.invalidate_proxy_class_with_custom_fields(self, metadata.name)
+          def #{name}_klass_out_of_date?
+            self.#{name}_klass.nil? || self.#{name}_klass.version != self.#{name}_custom_fields_version
           end
 
-          def invalidate_#{singular_name}_klass?
-            self.invalidate_#{singular_name}_klass_flag == true
+          def invalidate_#{name}_klass
+            self.invalidate_klass_with_custom_fields('#{name}')
           end
-        EOV
 
-        # mongoid tiny patch: for performance optimization (ie: we do want to invalidate klass with custom fields every time we save a field)
-        unless instance_methods.collect(&:to_s).include?('write_attributes_with_custom_fields')
+          def invalidate_#{name}_klass?
+            self.invalidate_klass_with_custom_fields?('#{name}')
+          end
 
-          class_eval do
-            def write_attributes_with_custom_fields(attrs = nil, guard_protected_attributes = true)
-              self.instance_variable_set(:@_writing_attributes_with_custom_fields, true)
-              self.write_attributes_without_custom_fields(attrs, guard_protected_attributes)
+          def rebuild_#{name}_relation
+            # puts "--> AFTER SAVE (#{name})"
+            if self.#{name}_klass_out_of_date?
+              # puts 'rebuild relation for #{name} after save'
+              self.rebuild_custom_fields_relation('#{name}')
             end
+          end
+
+          protected
 
-            alias_method_chain :write_attributes, :custom_fields
+          def bump_#{name}_custom_fields_version
+            # puts "--> BEFORE SAVE (#{name})"
+            self.bump_custom_fields_version('#{name}')
           end
 
-        end
+          def mark_#{name}_custom_fields_as_persisted
+            self.mark_custom_fields_as_persisted('#{name}')
+          end
 
-        if itself
-          class_eval <<-EOV
-            alias :self_custom_fields :#{singular_name}_custom_fields
-          EOV
-        end
+          def reset_#{name}_klass_invalidated_flag
+            self.reset_klass_with_custom_fields_invalidated_flag('#{name}')
+          end
 
+        EOV
       end
 
-      protected
-
-      def dynamic_custom_field_class_name(collection_name)
-        "#{self.name}#{collection_name.to_s.singularize.camelize}Field"
+      # Returns the class name of the custom field which is based both on the parent class name
+      # and the name of the relation in order to avoid name conflicts (with other classes)
+      #
+      # @param [ Metadata ] metadata The relation's old metadata.
+      #
+      # @return [ String ] The class name
+      #
+      def dynamic_custom_field_class_name(name)
+        "#{self.name}#{name.to_s.singularize.camelize}Field"
       end
 
       # An embedded relationship has to be defined on both side in order for it
       # to work properly. But because custom_field can be embedded in different
       # models that it's not aware of, we have to declare manually the definition
       # once we know the target class.
-      def declare_embedded_in_definition_in_custom_field(target_collection_name)
-        singular_name   = target_collection_name.to_s.singularize
-        klass_name      = self.dynamic_custom_field_class_name(target_collection_name)
+      #
+      # @param [ String, Symbol ] name The name of the relation.
+      #
+      # @return [ Field ] The new field class.
+      #
+      def declare_embedded_in_definition_in_custom_field(name)
+        klass_name = self.dynamic_custom_field_class_name(name)
 
         unless Object.const_defined?(klass_name)
           (klass = Class.new(::CustomFields::Field)).class_eval <<-EOF
-            embedded_in :#{self.name.underscore}, :inverse_of => :#{singular_name}_custom_fields
+            embedded_in :#{self.name.underscore}, :inverse_of => :#{name}_custom_fields
           EOF
 
           Object.const_set(klass_name, klass)
@@ -191,4 +345,6 @@ module CustomFields
 
   end
 
-end
+end
+
+

data/lib/custom_fields/extensions/active_support.rb

@@ -0,0 +1,12 @@
+unless ActiveSupport::Callbacks::ClassMethods.method_defined?(:without_callback)
+
+  module ActiveSupport::Callbacks::ClassMethods
+    def without_callback(*args, &block)
+      skip_callback(*args)
+      yield.tap do |result|
+        set_callback(*args)
+      end
+    end
+  end
+
+end

data/lib/custom_fields/extensions/mongoid/document.rb

@@ -1,9 +1,37 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
 
+  # # This is the base module for all domain objects that need to be persisted to
+  # # the database as documents.
+  # module Document
+  #
+  #   # Reloads the +Document+ attributes from the database. If the document has
+  #   # not been saved then an error will get raised if the configuration option
+  #   # was set.
+  #   #
+  #   # @example Reload the document.
+  #   #   person.reload
+  #   #
+  #   # @raise [ Errors::DocumentNotFound ] If the document was deleted.
+  #   #
+  #   # @return [ Document ] The document, reloaded.
+  #   def reload_with_custom_fields
+  #     reload_without_custom_fields.tap do
+  #       instance_variable_names.each do |name|
+  #         if name =~ /_proxy_class$/
+  #           remove_instance_variable("#{name}")
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   alias_method_chain :reload, :custom_fields
+  #
+  # end
+
   # This is the base module for all domain objects that need to be persisted to
   # the database as documents.
-  module Document
+  module Reloading
 
     # Reloads the +Document+ attributes from the database. If the document has
     # not been saved then an error will get raised if the configuration option

data/lib/custom_fields/extensions/mongoid/relations/accessors.rb

@@ -4,26 +4,27 @@ module Mongoid # :nodoc:
 
     module Accessors
 
-      # Create a relation from an object and metadata.
+      # Builds the related document and creates the relation based on the class
+      # enhanced by the custom_fields functionnality (if set up for the relation).
       #
-      # @example Create the relation.
-      #   person.create_relation(document, metadata)
-      #
-      # @param [ Document, Array<Document ] object The relation target.
-      # @param [ Metadata ] metadata The relation metadata.
+      # @param [ String, Symbol ] name The name of the relation.
+      # @param [ Hash, BSON::ObjectId ] object The id or attributes to use.
+      # @param [ Metadata ] metadata The relation's metadata.
+      # @param [ true, false ] building If we are in a build operation.
       #
       # @return [ Proxy ] The relation.
       #
       # @since 2.0.0.rc.1
-      def create_relation_with_custom_fields(object, metadata)
+      def build_with_custom_fields(name, object, metadata)
         if self.respond_to?(:custom_fields_for?) && self.custom_fields_for?(metadata.name)
+          # puts "[Accessors] build_with_custom_fields #{name}"
           metadata = self.clone_metadata_for_custom_fields(metadata)
         end
 
-        create_relation_without_custom_fields(object, metadata)
+        build_without_custom_fields(name, object, metadata)
       end
 
-      alias_method_chain :create_relation, :custom_fields
+      alias_method_chain :build, :custom_fields
     end
 
   end

data/lib/custom_fields/extensions/mongoid/relations/builders.rb

@@ -2,7 +2,6 @@ module Mongoid # :nodoc:
   module Relations #:nodoc:
 
     module Builders
-      extend ActiveSupport::Concern
 
       module ClassMethods #:nodoc:
 
@@ -13,8 +12,12 @@ module Mongoid # :nodoc:
                 metadata = self.clone_metadata_for_custom_fields(metadata)
               end
 
-              document = Factory.build(metadata.klass, args.first || {})
-              send("#{name}=", document, :binding => true)
+              attributes = args.first || {}
+              options = args.size > 1 ? args[1] : {}
+              document = Factory.build(metadata.klass, attributes, options)
+              _building do
+                send("#{name}=", document)
+              end
             end
           end
         end