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