Ticket #13997: 13997.3.diff

docs/ref/forms/widgets.txt

@@ -150 +150 @@
 
 .. class:: MultiWidget
 
-    Wrapper around multiple other widgets
+    Wrapper around multiple other widgets.
+
+    Here is an example of using the ``MultiWidget`` with the
+    ``us.forms.USPhoneNumberField`` in the ``localflavor`` package.
+
+    .. 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)
+                if any(values):
+                    values = (x.replace("-", "") for x in 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)
+
+    This widget would be used 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())
+
+Testing MultiWidgets
+====================
+
+A field using a MultiWidget splits form data into multiple form elements.
+In the form above, which defined a field called ``phone`` split into three
+widgets, the three rendered fields are named ``phone_0``, ``phone_1``,
+and ``phone_2``.
+
+The following gives an example of testing this form field.
+
+.. code-block:: python
+
+    class USSplitPhoneWidgetTest(TestCase):
+
+        def test_field_validation(self):
+
+            class TestPhoneForm(forms.Form):
+                phone = USPhoneNumberField(label="Phone",
+                     widget=gfaforms.fields.USSplitPhoneWidget())
+
+            form = TestPhoneForm(data={
+                "phone_0": "800",
+                "phone_1": "999",
+                "phone_2": "2000",
+            })
+            self.assertTrue(form.is_valid())
 
 .. class:: SplitDateTimeWidget