diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index dbdf109..fec52fa 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -150,7 +150,85 @@ commonly used groups of widgets:
.. 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 '(%s)%s-%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