Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added some clearer docstrings to MultiValueField and MultiWidget

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5575 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit acf0ff02e78105c67d2a66c7c898f572ae84fdc0 1 parent 510e545
@adrianholovaty adrianholovaty authored
Showing with 32 additions and 15 deletions.
  1. +7 −6 django/newforms/fields.py
  2. +25 −9 django/newforms/widgets.py
View
13 django/newforms/fields.py
@@ -482,17 +482,18 @@ def clean(self, value):
class MultiValueField(Field):
"""
- A Field that is composed of multiple Fields.
-
- Its clean() method takes a "decompressed" list of values. Each value in
+ A Field that aggregates the logic of multiple Fields.
+
+ Its clean() method takes a "decompressed" list of values, which are then
+ cleaned into a single value according to self.fields. Each value in
this list is cleaned by the corresponding field -- the first value is
cleaned by the first field, the second value is cleaned by the second
field, etc. Once all fields are cleaned, the list of clean values is
"compressed" into a single value.
- Subclasses should implement compress(), which specifies how a list of
- valid values should be converted to a single value. Subclasses should not
- have to implement clean().
+ Subclasses should not have to implement clean(). Instead, they must
+ implement compress(), which takes a list of valid values and returns a
+ "compressed" version of those values -- a single value.
You'll probably want to use this with MultiWidget.
"""
View
34 django/newforms/widgets.py
@@ -304,19 +304,28 @@ class MultiWidget(Widget):
"""
A widget that is composed of multiple widgets.
- Its render() method takes a "decompressed" list of values, not a single
- value. Each value in this list is rendered in the corresponding widget --
- the first value is rendered in the first widget, the second value is
- rendered in the second widget, etc.
+ Its render() method is different than other widgets', because it has to
+ figure out how to split a single value for display in multiple widgets.
+ The ``value`` argument can be one of two things:
- Subclasses should implement decompress(), which specifies how a single
- value should be converted to a list of values. Subclasses should not
- have to implement clean().
+ * A list.
+ * A normal value (e.g., a string) that has been "compressed" from
+ a list of values.
+
+ In the second case -- i.e., if the value is NOT a list -- render() will
+ first "decompress" the value into a list before rendering it. It does so by
+ calling the decompress() method, which MultiWidget subclasses must
+ implement. This method takes a single "compressed" value and returns a
+ list.
+
+ When render() does its HTML rendering, each value in the list is rendered
+ with the corresponding widget -- the first value is rendered in the first
+ widget, the second value is rendered in the second widget, etc.
Subclasses may implement format_output(), which takes the list of rendered
- widgets and returns HTML that formats them any way you'd like.
+ widgets and returns a string of HTML that formats them any way you'd like.
- You'll probably want to use this with MultiValueField.
+ You'll probably want to use this class with MultiValueField.
"""
def __init__(self, widgets, attrs=None):
self.widgets = [isinstance(w, type) and w() or w for w in widgets]
@@ -351,6 +360,13 @@ def value_from_datadict(self, data, name):
return [widget.value_from_datadict(data, name + '_%s' % i) for i, widget in enumerate(self.widgets)]
def format_output(self, rendered_widgets):
+ """
+ Given a list of rendered widgets (as strings), returns a Unicode string
+ representing the HTML for the whole lot.
+
+ This hook allows you to format the HTML design of the widgets, if
+ needed.
+ """
return u''.join(rendered_widgets)
def decompress(self, value):
Please sign in to comment.
Something went wrong with that request. Please try again.