MONGOID-5264 add :present option to localized fields (#5408)

* MONGOID-5264 add :present option to localize

* MONGOID-5264 change present? to localize_present?

* MONGOID-5264 add tests and fix present

* MONGOID-5264 add docs and release notes

* MONGOID-5264 potentially fix tests

* MONGOID-5264 fix docs

* MONGOID-5264 update the docstring

* MONGOID-5264 reset fallbacks after setting

* Update docs/reference/fields.txt

Co-authored-by: Oleg Pudeyev <[email protected]>

* MONGOID-5264 answer comments

* Update lib/mongoid/attributes.rb

Co-authored-by: Oleg Pudeyev <[email protected]>

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: neilshweky

docs/reference/fields.txt

@@ -1396,6 +1396,42 @@ You can get and set all the translations at once by using the corresponding ``_t
      { "en" => "Marvelous!", "de" => "Wunderbar!" }
 
 
+.. _present-fields:
+
+Localize ``:present`` Field Option
+----------------------------------
+
+Mongoid supports the ``:present`` option when creating a localized field:
+
+.. code-block:: ruby
+
+   class Product
+     include Mongoid::Document
+     field :description, localize: :present
+   end
+
+This option automatically removes ``blank`` values (i.e. those that return true
+for the ``blank?`` method) from the ``_translations`` hash:
+
+.. code-block:: ruby
+
+   I18n.default_locale = :en
+   product = Product.new
+   product.description = "Marvelous!"
+   I18n.locale = :de
+   product.description = "Fantastisch!"
+
+   product.description_translations
+   # { "en" => "Marvelous!", "de" => "Fantastisch!" }
+
+   product.description = ""
+   product.description_translations
+   # { "en" => "Marvelous!" }
+
+When the empty string is written for the ``:de`` locale, the ``"de"`` key is
+removed from the ``_translations`` hash instead of writing the empty string.
+
+
 Fallbacks
 ---------
 

docs/release-notes/mongoid-8.1.txt

@@ -99,3 +99,20 @@ specific version:
 This is helpful for upgrading between versions. See the section on
 :ref:`Version Based Default Configuration <load-defaults>` for more details on
 how to use this feature to make upgrading between Mongoid versions easier.
+
+
+Added ``:present`` option to localized fields
+---------------------------------------------
+
+The ``:present`` option was added to localized fields for removing blank values
+from the ``_translations`` hash:
+
+.. code-block:: ruby
+
+   class Product
+     include Mongoid::Document
+     field :description, localize: :present
+   end
+
+See the section on :ref:`Localize :present Field Option <present-fields>` for
+more details on how these are used.

lib/mongoid/attributes.rb

@@ -177,8 +177,14 @@ def write_attribute(name, value)
             attribute_will_change!(field_name)
           end
           if localized
-            attributes[field_name] ||= {}
-            attributes[field_name].merge!(typed_value)
+            present = fields[field_name].try(:localize_present?)
+            loc_key, loc_val = typed_value.first
+            if present && loc_val.blank?
+              attributes[field_name]&.delete(loc_key)
+            else
+              attributes[field_name] ||= {}
+              attributes[field_name].merge!(typed_value)
+            end
           else
             attributes[field_name] = typed_value
           end

lib/mongoid/fields.rb

@@ -802,18 +802,18 @@ def field_for(name, options)
         Fields::Standard.new(name, opts)
       end
 
-       # Get the class for the given type.
-       #
-       # @param [ Symbol ] name The name of the field.
-       # @param [ Symbol | Class ] type The type of the field.
-       #
-       # @return [ Class ] The type of the field.
-       #
-       # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
-       #   type.
-       #
-       # @api private
-       def retrieve_and_validate_type(name, type)
+      # Get the class for the given type.
+      #
+      # @param [ Symbol ] name The name of the field.
+      # @param [ Symbol | Class ] type The type of the field.
+      #
+      # @return [ Class ] The type of the field.
+      #
+      # @raises [ Mongoid::Errors::InvalidFieldType ] if given an invalid field
+      #   type.
+      #
+      # @api private
+      def retrieve_and_validate_type(name, type)
         type_mapping = TYPE_MAPPINGS[type]
         result = type_mapping || unmapped_type(type)
         if !result.is_a?(Class)

lib/mongoid/fields/localized.rb

@@ -29,6 +29,16 @@ def localized?
         true
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        options[:localize] == :present
+      end
+
       # Convert the provided string into a hash for the locale.
       #
       # @example Serialize the value.

lib/mongoid/fields/standard.rb

@@ -97,6 +97,16 @@ def localized?
         false
       end
 
+      # Is the localized field enforcing values to be present?
+      #
+      # @example Is the localized field enforcing values to be present?
+      #   field.localize_present?
+      #
+      # @return [ true | false ] If the field enforces present.
+      def localize_present?
+        false
+      end
+
       # Get the metadata for the field if its a foreign key.
       #
       # @example Get the metadata.

spec/mongoid/fields/localized_spec.rb

@@ -124,8 +124,11 @@
 
             context "when fallbacks are defined" do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [ :de, :en, :es ]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               context "when the first fallback translation exists" do
@@ -164,8 +167,11 @@
 
             context "when no fallbacks are defined" do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [ :de ]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               let(:value) do
@@ -179,8 +185,11 @@
 
             context 'when fallbacks are empty' do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [ ]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               let(:value) do
@@ -282,8 +291,11 @@
 
             context "when fallbacks are defined" do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [ :de, :en, :es ]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               context 'when fallbacks are enabled' do
@@ -340,8 +352,11 @@
 
             context "when no fallbacks are defined" do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [ :de ]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               let(:value) do
@@ -485,8 +500,11 @@
 
             context "when the value is false" do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [:en, :es]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               let(:field) do
@@ -504,8 +522,11 @@
 
             context "when the value is true" do
 
-              before do
+              around do |example|
+                prev_fallbacks = I18n.fallbacks.dup
                 ::I18n.fallbacks[:de] = [:en, :es]
+                example.run
+                I18n.fallbacks = prev_fallbacks
               end
 
               let(:field) do
@@ -525,4 +546,37 @@
       end
     end
   end
+
+  describe "localize: :present" do
+
+    let(:field) do
+      described_class.new(:description, localize: :present, type: String)
+    end
+
+    context "when setting the localize to present" do
+
+      it "is localized?" do
+        expect(field.localized?).to be true
+      end
+
+      it "is localize_present?" do
+        expect(field.localize_present?).to be true
+      end
+    end
+
+    context "when localize is not localize_present" do
+
+      let(:field) do
+        described_class.new(:description, localize: true, type: String)
+      end
+
+      it "is localized?" do
+        expect(field.localized?).to be true
+      end
+
+      it "is not localize_present?" do
+        expect(field.localize_present?).to be false
+      end
+    end
+  end
 end