Move DSL to top-level config

Author: johnnyshields

docs/reference/fields.txt

@@ -921,8 +921,8 @@ You may optionally declare a mapping for the new field type in an initializer:
 
   # in /config/initializers/mongoid_custom_fields.rb
 
-  Mongoid::Fields.configure do
-    define_type :point, Point
+  Mongoid.configure do |config|
+    config.define_field_type :point, Point
   end
 
 
@@ -1021,8 +1021,8 @@ specifiying its handler function as a block:
 
   # in /config/initializers/mongoid_custom_fields.rb
 
-  Mongoid::Fields.configure do
-    option :required do |model, field, value|
+  Mongoid.configure do |config|
+    config.define_field_option :required do |model, field, value|
       model.validates_presence_of field.name if value
     end
   end

docs/release-notes/mongoid-8.0.txt

@@ -322,15 +322,42 @@ Mongoid 8.0 adds the ability to define custom ``field :type`` Symbol values as f
 
 .. code-block:: ruby
 
-  # in /config/initializers/mongoid_custom_fields.rb
+  # in /config/initializers/mongoid.rb
 
-  Mongoid::Fields.configure do
-    define_type :point, Point
+  Mongoid.configure do |config|
+    config.define_field_type :point, Point
   end
 
 Refer to the :ref:`docs <http://docs.mongodb.org/manual/reference/fields/#custom-field-types>` for details.
 
 
+Support for Defining Custom Field Options via Top-Level Config
+--------------------------------------------------------------
+
+Mongoid 8.0 adds the ability to define custom ``field`` options as follows:
+
+.. code-block:: ruby
+
+  # in /config/initializers/mongoid.rb
+
+  Mongoid.configure do |config|
+    config.define_field_option :required do |model, field, value|
+      model.validates_presence_of field.name if value
+    end
+  end
+
+In Mongoid 7, this was possible with the following legacy syntax. Users are
+recommended to migrate to the Mongoid 8.0 syntax above.
+
+.. code-block:: ruby
+
+  Mongoid::Fields.option :required do |model, field, value|
+    model.validates_presence_of field.name if value
+  end
+
+Refer to the :ref:`docs <http://docs.mongodb.org/manual/reference/fields/#custom-field-options>` for details.
+
+
 ``#pluck`` on Embedded Criteria Returns ``nil`` Values
 ------------------------------------------------------
 

lib/mongoid/config.rb

@@ -314,6 +314,43 @@ def running_with_passenger?
       @running_with_passenger ||= defined?(PhusionPassenger)
     end
 
+    # Defines a field type mapping, for later use in field :type option.
+    #
+    # @example
+    #   Mongoid.configure do
+    #     define_field_type :point, Point
+    #   end
+    #
+    # @param [ Symbol | String ] type_name The identifier of the
+    #   defined type. This identifier may be accessible as either a
+    #   Symbol or a String regardless of the type passed to this method.
+    # @param [ Module ] klass the class of the defined type, which must
+    #   include mongoize, demongoize, and evolve methods.
+    def define_field_type(type_name, klass)
+      Mongoid::Fields::FieldTypes.define_type(type_name, klass)
+    end
+
+    # Defines an option for the field macro, which runs the handler
+    # provided as a block.
+    #
+    # No assumptions are made about what functionality the handler might
+    # perform, so it will always be called if the `option_name` key is
+    # provided in the field definition -- even if it is false or nil.
+    #
+    # @example
+    #   Mongoid.configure do
+    #     define_field_option :required do |model, field, value|
+    #       model.validates_presence_of field.name if value
+    #     end
+    #   end
+    #
+    # @param [ Symbol ] option_name the option name to match against
+    # @param [ Proc ] block the handler to execute when the option is
+    #   provided.
+    def define_field_option(option_name, &block)
+      Mongoid::Fields.option(option_name, &block)
+    end
+
     private
 
     def set_log_levels

lib/mongoid/fields.rb

@@ -257,33 +257,6 @@ def validate_writable_field_name!(name)
 
     class << self
 
-      # DSL method used for configuration readability, typically in
-      # an initializer.
-      #
-      # @example
-      #   Mongoid::Fields.configure do
-      #     # do configuration
-      #   end
-      def configure(&block)
-        instance_exec(&block)
-      end
-
-      # Defines a field type mapping, for later use in field :type option.
-      #
-      # @example
-      #   Mongoid::Fields.configure do
-      #     define_type :point, Point
-      #   end
-      #
-      # @param [ Symbol | String ] field_type The identifier of the
-      #   defined type. This identifier may be accessible as either a
-      #   Symbol or a String regardless of the type passed to this method.
-      # @param [ Module ] klass the class of the defined type, which must
-      #   include mongoize, demongoize, and evolve methods.
-      def define_type(field_type, klass)
-        Fields::FieldTypes.define_type(field_type, klass)
-      end
-
       # Stores the provided block to be run when the option name specified is
       # defined on a field.
       #

spec/mongoid/fields_spec.rb

@@ -1933,61 +1933,6 @@ class DiscriminatorChild2 < DiscriminatorParent
     end
   end
 
-  describe '.configure DSL' do
-
-    context '.type method' do
-      around do |example|
-        klass = Mongoid::Fields::FieldTypes
-        klass.instance_variable_set(:@mapping, klass::DEFAULT_MAPPING.dup)
-        example.run
-        klass.instance_variable_set(:@mapping, klass::DEFAULT_MAPPING.dup)
-      end
-
-      it 'can define a custom type' do
-        described_class.configure do
-          define_type :my_type, Integer
-        end
-
-        expect(described_class::FieldTypes.get(:my_type)).to eq Integer
-      end
-
-      it 'can override and existing type' do
-        described_class.configure do
-          define_type :integer, String
-        end
-
-        expect(described_class::FieldTypes.get(:integer)).to eq String
-      end
-    end
-
-    context '.option method' do
-      after do
-        described_class.instance_variable_set(:@options, {})
-      end
-
-      it 'can define a custom field option' do
-        described_class.configure do
-          option :my_required do |model, field, value|
-            model.validates_presence_of field.name if value
-          end
-        end
-
-        klass = Class.new do
-          include Mongoid::Document
-          field :my_field, my_required: true
-
-          def self.model_name
-            OpenStruct.new(human: 'Klass')
-          end
-        end
-
-        instance = klass.new
-        expect(instance.valid?).to eq false
-        expect(instance.errors.full_messages).to eq ["My field can't be blank"]
-      end
-    end
-  end
-
   describe '::TYPE_MAPPINGS' do
     it 'returns the default mapping' do
       expect(described_class::TYPE_MAPPINGS).to eq ::Mongoid::Fields::FieldTypes::DEFAULT_MAPPING