Ticket #13997: 13997.diff

docs/ref/forms/widgets.txt

@@ -150 +150 @@
 
 .. class:: MultiWidget
 
-    Wrapper around multiple other widgets
+    Wrapper around multiple other widgets. This is usually used in conjunction
+    with the ``MultiValueField``.
+
+.. note::
+
+    If you want to use a ``MultiWidget`` for a field that is not a subclass
+    of :class:`MultiValueField`, such as the ``us.forms.USPhoneNumberField`` from
+    the ``localflavor`` package, then you must override the ``value_from_datadict``
+    method of your widget to return a single value appropriate for the
+    field.
+
+    .. code-block:: python
+
+        class USSplitPhoneWidget(forms.MultiWidget):
+
+            widgets = (
+                forms.TextInput(attrs={'size':'3','maxlength':'3'}),
+                forms.TextInput(attrs={'size':'3','maxlength':'3'}),
+                forms.TextInput(attrs={'size':'4','maxlength':'4'}),
+            )
+
+            def decompress(self, value):
+                """
+                Accepts a single value which is extracted to populate the
+                provided widgets.
+                """
+                if value:
+                    return value.split('-')
+                return (None,None,None)
+
+            def value_from_datadict(self, data, files, name):
+                """
+                Modify the widget to return a single value for the
+                USPhoneNumberField.
+                """
+                values = super(USSplitPhoneWidget, self).value_from_datadict(data, files, name)
+                values = (x.replace("-", "") for x in values)
+                if all(values):
+                    return u'%s-%s-%s' % tuple(values)
+                return ""
+
+            def format_output(self, rendered_widgets):
+                return '<span class="lparen">(</span>%s<span class="rparen">)</span>%s<span class="phone-dash">-</span>%s' % tuple(rendered_widgets)
 
 .. class:: SplitDateTimeWidget