[1.10.x] Fixed #27186 -- Fixed model form default fallback for MultiWidget, FileInput, SplitDateTimeWidget, SelectDateWidget, and SplitArrayWidget.

Thanks Matt Westcott for the review.

Backport of 3507d4e773aa9ff2336e7230ba231c4ba6eb568f from master

3 files changed, 31 insertions, 5 deletions

diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 0bc23aab66..fde7806b02 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -271,6 +271,21 @@ foundation for custom widgets.
         customize it and add expensive processing, you should implement some
         caching mechanism yourself.
 
+    .. method:: value_omitted_from_data(data, files, name)
+
+        .. versionadded:: 1.10.2
+
+        Given ``data`` and ``files`` dictionaries and this widget's name,
+        returns whether or not there's data or files for the widget.
+
+        The method's result affects whether or not a field in a model form
+        :ref:`falls back to its default <topics-modelform-save>`.
+
+        A special case is :class:`~django.forms.CheckboxInput`, which always
+        returns ``False`` because an unchecked checkbox doesn't appear in the
+        data of an HTML form submission, so it's unknown whether or not the
+        user actually submitted a value.
+
 ``MultiWidget``
 ---------------
 
diff --git a/docs/releases/1.10.2.txt b/docs/releases/1.10.2.txt
index 8c031d37f5..222323c245 100644
--- a/docs/releases/1.10.2.txt
+++ b/docs/releases/1.10.2.txt
@@ -17,3 +17,8 @@ Bugfixes
 
 * Disabled system check for URL patterns beginning with a '/' when
   ``APPEND_SLASH=False`` (:ticket:`27238`).
+
+* Fixed model form ``default`` fallback for ``MultiWidget``, ``FileInput``,
+  ``SplitDateTimeWidget``, ``SelectDateWidget``, and ``SplitArrayWidget``
+  (:ticket:`27186`). Custom widgets affected by this issue may need to
+  implement a :meth:`~django.forms.Widget.value_omitted_from_data` method.
diff --git a/docs/topics/forms/modelforms.txt b/docs/topics/forms/modelforms.txt
index e2b57fe410..3d5bc746fe 100644
--- a/docs/topics/forms/modelforms.txt
+++ b/docs/topics/forms/modelforms.txt
@@ -299,6 +299,8 @@ to the ``error_messages`` dictionary of the ``ModelForm``’s inner ``Meta`` cla
                 }
             }
 
+.. _topics-modelform-save:
+
 The ``save()`` method
 ---------------------
 
@@ -333,11 +335,11 @@ doesn't validate -- i.e., if ``form.errors`` evaluates to ``True``.
 If an optional field doesn't appear in the form's data, the resulting model
 instance uses the model field :attr:`~django.db.models.Field.default`, if
 there is one, for that field. This behavior doesn't apply to fields that use
-:class:`~django.forms.CheckboxInput` (or any custom widget with
-``dont_use_model_field_default_for_empty_data=True``) since an unchecked
-checkbox doesn't appear in the data of an HTML form submission. Use a custom
-form field or widget if you're designing an API and want the default fallback
-for a ``BooleanField``.
+:class:`~django.forms.CheckboxInput` (or any custom widget whose
+:meth:`~django.forms.Widget.value_omitted_from_data` method always returns
+``False``) since an unchecked checkbox doesn't appear in the data of an HTML
+form submission. Use a custom form field or widget if you're designing an API
+and want the default fallback for a :class:`~django.db.models.BooleanField`.
 
 .. versionchanged:: 1.10.1
 
@@ -345,6 +347,10 @@ for a ``BooleanField``.
     :class:`~django.forms.CheckboxInput` which means that unchecked checkboxes
     receive a value of ``True`` if that's the model field default.
 
+.. versionchanged:: 1.10.2
+
+    The :meth:`~django.forms.Widget.value_omitted_from_data` method was added.
+
 This ``save()`` method accepts an optional ``commit`` keyword argument, which
 accepts either ``True`` or ``False``. If you call ``save()`` with
 ``commit=False``, then it will return an object that hasn't yet been saved to