MONGOID-5336

Author: johnnyshields

docs/reference/fields.txt

@@ -897,6 +897,17 @@ can use in our model class as follows:
     field :location, type: Point
   end
 
+You may optionally declare a symbol mapping for the new field type in an initializer:
+
+.. code-block:: ruby
+
+  # in /config/initializers/mongoid_custom_fields.rb
+
+  Mongoid::Fields.configure do
+    type :point, Point
+  end
+
+
 Then make a Ruby class to represent the type. This class must define methods
 used for MongoDB serialization and deserialization as follows:
 
@@ -992,8 +1003,10 @@ specifiying its handler function as a block:
 
   # in /config/initializers/mongoid_custom_fields.rb
 
-  Mongoid::Fields.option :required do |model, field, value|
-    model.validates_presence_of field if value
+  Mongoid::Fields.configure do
+    option :required do |model, field, value|
+      model.validates_presence_of field.name if value
+    end
   end
 
 Then, use it your model class:

docs/release-notes/mongoid-8.0.txt

@@ -303,6 +303,22 @@ Mongoid 7 behavior:
   end
 
 
+Support for Defining Custom Field Type Values
+---------------------------------------------
+
+Mongoid 8.0 adds the ability to define custom ``field :type`` Symbol values as follows:
+
+.. code-block:: ruby
+
+  # in /config/initializers/mongoid_custom_fields.rb
+
+  Mongoid::Fields.configure do
+    type :point, Point
+  end
+
+Refer to the :ref:`docs <http://docs.mongodb.org/manual/reference/fields/#custom-field-types>` for details.
+
+
 Removed ``:drop_dups`` Option from Indexes
 ------------------------------------------
 

lib/config/locales/en.yml

@@ -164,8 +164,10 @@ en:
           resolution: "When defining the field :%{name} on '%{klass}', please provide
             valid options for the field. These are currently: %{valid}. If you
             meant to define a custom field option, please do so first as follows:\n\n
-            \_\_Mongoid::Fields.option :%{option} do |model, field, value|\n
-            \_\_\_\_# Your logic here...\n
+            \_\_Mongoid::Fields.configure do\n
+            \_\_\_\_option :%{option} do |model, field, value|\n
+            \_\_\_\_\_\_# Your logic here...\n
+            \_\_\_\_end\n
             \_\_end\n
             \_\_class %{klass}\n
             \_\_\_\_include Mongoid::Document\n
@@ -174,12 +176,21 @@ en:
             Refer to:
             https://docs.mongodb.com/mongoid/current/reference/fields/#custom-field-options"
         invalid_field_type:
-          message: "Invalid field type %{type_inspection} for field '%{field}' on model '%{klass}'."
-          summary: "Model '%{klass}' defines a field '%{field}' with an unknown type value
-            %{type_inspection}."
-          resolution: "Please provide a valid type value for the field.
+          message: "Invalid field type %{type_inspection} for field :%{field} on model '%{klass}'."
+          summary: "Model '%{klass}' defines a field :%{field} with an unknown :type value
+            %{type_inspection}. This value is neither present in Mongoid's default type mapping,
+            nor defined in a custom field type mapping."
+          resolution: "Please provide a valid :type value for the field. If you
+            meant to define a custom field type, please do so first as follows:\n\n
+            \_\_Mongoid::Fields.configure do\n
+            \_\_\_\_type %{type_inspection}, YourTypeClass
+            \_\_end\n
+            \_\_class %{klass}\n
+            \_\_\_\_include Mongoid::Document\n
+            \_\_\_\_field :%{field}, type: %{type_inspection}\n
+            \_\_end\n\n
             Refer to:
-            https://docs.mongodb.com/mongoid/current/reference/fields/#using-symbols-or-strings-instead-of-classes"
+            https://docs.mongodb.com/mongoid/current/reference/fields/#custom-field-types"
         invalid_includes:
           message: "Invalid includes directive: %{klass}.includes(%{args})"
           summary: "Eager loading in Mongoid only supports providing arguments

lib/mongoid/fields.rb

@@ -4,6 +4,7 @@
 require "mongoid/fields/foreign_key"
 require "mongoid/fields/localized"
 require "mongoid/fields/validators"
+require "mongoid/fields/field_types"
 
 module Mongoid
 
@@ -14,27 +15,6 @@ module Fields
     StringifiedSymbol = Mongoid::StringifiedSymbol
     Boolean = Mongoid::Boolean
 
-    # For fields defined with symbols use the correct class.
-    TYPE_MAPPINGS = {
-      array: Array,
-      big_decimal: BigDecimal,
-      binary: BSON::Binary,
-      boolean: Mongoid::Boolean,
-      date: Date,
-      date_time: DateTime,
-      float: Float,
-      hash: Hash,
-      integer: Integer,
-      object_id: BSON::ObjectId,
-      range: Range,
-      regexp: Regexp,
-      set: Set,
-      string: String,
-      stringified_symbol: StringifiedSymbol,
-      symbol: Symbol,
-      time: Time
-    }.with_indifferent_access
-
     # Constant for all names of the _id field in a document.
     #
     # This does not include aliases of _id field.
@@ -243,6 +223,27 @@ def using_object_ids?
 
     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
+      #     type :point, Point
+      #   end
+      def type(symbol, klass)
+        Fields::FieldTypes.define(symbol, klass)
+      end
+
       # Stores the provided block to be run when the option name specified is
       # defined on a field.
       #
@@ -251,8 +252,10 @@ class << self
       # provided in the field definition -- even if it is false or nil.
       #
       # @example
-      #   Mongoid::Fields.option :required do |model, field, value|
-      #     model.validates_presence_of field if value
+      #   Mongoid::Fields.configure do
+      #     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
@@ -729,22 +732,16 @@ def remove_defaults(name)
 
       def field_for(name, options)
         opts = options.merge(klass: self)
-        type_mapping = TYPE_MAPPINGS[options[:type]]
-        opts[:type] = type_mapping || unmapped_type(options)
-        unless opts[:type].is_a?(Class)
-          raise Errors::InvalidFieldType.new(self, name, options[:type])
-        end
+        opts[:type] = field_type_klass_for(name, options[:type])
         return Fields::Localized.new(name, opts) if options[:localize]
         return Fields::ForeignKey.new(name, opts) if options[:identity]
         Fields::Standard.new(name, opts)
       end
 
-      def unmapped_type(options)
-        if "Boolean" == options[:type].to_s
-          Mongoid::Boolean
-        else
-          options[:type] || Object
-        end
+      def field_type_klass_for(field, type)
+        klass = Fields::FieldTypes.get(type)
+        return klass if klass
+        raise Mongoid::Errors::InvalidFieldType.new(self.name, field, type)
       end
     end
   end

lib/mongoid/fields/field_types.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Fields
+
+    # Singleton module which contains a cache for field type definitions.
+    # Custom field types can be configured.
+    module FieldTypes
+      extend self
+
+      # For fields defined with symbols use the correct class.
+      DEFAULT_MAPPING = {
+        array: Array,
+        bigdecimal: BigDecimal,
+        big_decimal: BigDecimal,
+        binary: BSON::Binary,
+        boolean: Mongoid::Boolean,
+        date: Date,
+        datetime: DateTime,
+        date_time: DateTime,
+        decimal128: BSON::Decimal128,
+        double: Float,
+        float: Float,
+        hash: Hash,
+        integer: Integer,
+        object: Object,
+        object_id: BSON::ObjectId,
+        range: Range,
+        regexp: Regexp,
+        set: Set,
+        string: String,
+        stringified_symbol: Mongoid::StringifiedSymbol,
+        symbol: Symbol,
+        time: Time,
+        time_with_zone: ActiveSupport::TimeWithZone
+      }.with_indifferent_access.freeze
+
+      def get(value)
+        value = value.to_sym if value.is_a?(String)
+        mapping[value] || handle_unmapped_type(value)
+      end
+
+      def define(symbol, klass)
+        mapping[symbol.to_sym] = klass
+      end
+
+      delegate :delete, to: :mapping
+
+      private
+
+      def mapping
+        @mapping ||= DEFAULT_MAPPING.dup
+      end
+
+      def handle_unmapped_type(type)
+        return Object if type.nil?
+
+        if type.is_a?(Module)
+          return Mongoid::Boolean if type.to_s == 'Boolean'
+          return type
+        end
+
+        nil
+      end
+    end
+  end
+end

spec/mongoid/errors/invalid_field_type_spec.rb

@@ -17,13 +17,13 @@
 
       it "contains the problem in the message" do
         expect(error.message).to include(
-          "Invalid field type :stringgy for field 'first_name' on model 'Person'."
+          "Invalid field type :stringgy for field :first_name on model 'Person'."
         )
       end
 
       it "contains the summary in the message" do
         expect(error.message).to include(
-          "Model 'Person' defines a field 'first_name' with an unknown type value :stringgy."
+          "Model 'Person' defines a field :first_name with an unknown :type value :stringgy."
         )
       end
     end
@@ -35,20 +35,20 @@
 
       it "contains the problem in the message" do
         expect(error.message).to include(
-          %q,Invalid field type "stringgy" for field 'first_name' on model 'Person'.,
+          %q,Invalid field type "stringgy" for field :first_name on model 'Person'.,
         )
       end
 
       it "contains the summary in the message" do
         expect(error.message).to include(
-          %q,Model 'Person' defines a field 'first_name' with an unknown type value "stringgy".,
+          %q,Model 'Person' defines a field :first_name with an unknown :type value "stringgy".,
         )
       end
     end
 
     it "contains the resolution in the message" do
       expect(error.message).to include(
-        'Please provide a valid type value for the field.'
+        'Please provide a valid :type value for the field.'
       )
     end
   end