Ticket #13997: 13997.2.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):
+            """
+            A widget that splits phone number input into three fields.
+            """
+            def __init__(self, widgets=None, attrs=None):
+                if not widgets:
+                    widgets = (
+                        forms.TextInput(attrs={'size':'3','maxlength':'3'}),
+                        forms.TextInput(attrs={'size':'3','maxlength':'3'}),
+                        forms.TextInput(attrs={'size':'4','maxlength':'4'}),
+                    )
+                super(USSplitPhoneWidget, self).__init__(widgets, attrs)
+
+            def decompress(self, value):
+                """
+                Accepts a single value which is extracted to populate the
+                provided widgets.
+                """
+                if value:
+                    return value.split('-')
+                return ("","","")
+
+            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)
+                return u'%s-%s-%s' % tuple(values)
+
+            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)
+
+    You would use this widget in a form as follows:
+
+    .. code-block:: python
+
+        from django.contrib.localflavor.us.forms import USPhoneNumberField
+
+        class MyForm(forms.Form):
+            phone = USPhoneNumberField(label="Phone",
+                 widget=USSplitPhoneWidget())
 
 .. class:: SplitDateTimeWidget