Ticket #16264: django-16264.diff

docs/ref/forms/widgets.txt

@@ -11 +11 @@
 handles the rendering of the HTML, and the extraction of data from a GET/POST
 dictionary that corresponds to the widget.
 
-Django provides a representation of all the basic HTML widgets, plus some
-commonly used groups of widgets:
-
-.. class:: TextInput
-
-    Text input: ``<input type='text' ...>``
-
-.. class:: PasswordInput
-
-    Password input: ``<input type='password' ...>``
-
-    Takes one optional argument:
-
-    .. attribute:: PasswordInput.render_value
-
-        Determines whether the widget will have a value filled in when the
-        form is re-displayed after a validation error (default is ``False``).
-
-.. versionchanged:: 1.3
-    The default value for
-    :attr:`~PasswordInput.render_value` was
-    changed from ``True`` to ``False``
-
-.. class:: HiddenInput
-
-    Hidden input: ``<input type='hidden' ...>``
-
-.. class:: MultipleHiddenInput
-
-    Multiple ``<input type='hidden' ...>`` widgets.
-
-.. class:: FileInput
-
-    File upload input: ``<input type='file' ...>``
-
-.. class:: ClearableFileInput
-
-    .. versionadded:: 1.3
-
-    File upload input: ``<input type='file' ...>``, with an additional checkbox
-    input to clear the field's value, if the field is not required and has
-    initial data.
-
-.. class:: DateInput
-
-    Date input as a simple text box: ``<input type='text' ...>``
-
-    Takes one optional argument:
-
-    .. attribute:: DateInput.format
-
-        The format in which this field's initial value will be displayed.
-
-    If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.
-
-.. class:: DateTimeInput
-
-    Date/time input as a simple text box: ``<input type='text' ...>``
-
-    Takes one optional argument:
-
-    .. attribute:: DateTimeInput.format
-
-        The format in which this field's initial value will be displayed.
-
-    If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
-    %H:%M:%S'``.
-
-.. class:: TimeInput
-
-    Time input as a simple text box: ``<input type='text' ...>``
-
-    Takes one optional argument:
-
-    .. attribute:: TimeInput.format
-
-        The format in which this field's initial value will be displayed.
-
-    If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
-
-.. class:: Textarea
-
-    Text area: ``<textarea>...</textarea>``
-
-.. class:: CheckboxInput
-
-    Checkbox: ``<input type='checkbox' ...>``
-
-    Takes one optional argument:
-
-    .. attribute:: CheckboxInput.check_test
-
-        A callable that takes the value of the CheckBoxInput
-        and returns ``True`` if the checkbox should be checked for
-        that value.
-
-.. class:: Select
-
-    Select widget: ``<select><option ...>...</select>``
-
-    Requires that your field provides :attr:`~Field.choices`.
-
-.. class:: NullBooleanSelect
-
-    Select widget with options 'Unknown', 'Yes' and 'No'
-
-.. class:: SelectMultiple
-
-    Select widget allowing multiple selection: ``<select
-    multiple='multiple'>...</select>``
-
-    Requires that your field provides :attr:`~Field.choices`.
-
-.. class:: RadioSelect
-
-    A list of radio buttons:
-
-    .. code-block:: html
-
-        <ul>
-          <li><input type='radio' ...></li>
-          ...
-        </ul>
-
-    Requires that your field provides :attr:`~Field.choices`.
-
-.. class:: CheckboxSelectMultiple
-
-    A list of checkboxes:
-
-    .. code-block:: html
-
-        <ul>
-          <li><input type='checkbox' ...></li>
-          ...
-        </ul>
-
-.. class:: MultiWidget
-
-    Wrapper around multiple other widgets
-
-.. class:: SplitDateTimeWidget
-
-    Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``
-    for the time.
-
-    Takes two optional arguments, ``date_format`` and ``time_format``, which
-    work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
-
-.. currentmodule:: django.forms.extras.widgets
-
-.. class:: SelectDateWidget
-
-    Wrapper around three select widgets: one each for month, day, and year.
-    Note that this widget lives in a separate file from the standard widgets.
-
-    Takes one optional argument:
-
-    .. attribute:: List.years
-
-        An optional list/tuple of years to use in the "year" select box.
-        The default is a list containing the current year and the next 9 years.
-
-    .. code-block:: python
-
-        from django.forms.extras.widgets import SelectDateWidget
-
-        date = forms.DateField(widget=SelectDateWidget())
-
 Specifying widgets
 ------------------
-.. currentmodule:: django.forms
-
-.. attribute:: Form.widget
 
 Whenever you specify a field on a form, Django will use a default widget
 that is appropriate to the type of data that is to be displayed. To find
 which widget is used on which field, see the documentation for the
 built-in Field classes.
 
-However, if you want to use a different widget for a field, you can -
+However, if you want to use a different widget for a field, you can
 just use the 'widget' argument on the field definition. For example::
 
     from django import forms
@@ -204 +32 @@
 This would specify a form with a comment that uses a larger Textarea widget,
 rather than the default TextInput widget.
 
+
+Setting arguments for widgets
+-----------------------------
+
+Some widgets take over arguments from the fields they represent, for example
+:class:`RadioSelect` or :class:`MultipleChoiceField` will use the choices of 
+the underlying field. Some widgets have optional extra arguments; they can be 
+set when defining the widget on the field. The reference below describes which 
+options can be set.
+
+In this example, the years attribute is set for a 
+:class:`django.forms.widgets.extras.SelectDateWidget`: ::
+
+    YEAR_CHOICES = ('2010', '2009',)
+    RADIO_CHOICES = (('1','Radio 1',), ('2','Radio 2',),)
+    CHECKBOX_CHOICES = (('1','The first choice',), ('2','The Second Choice',),)
+
+    class SimpleForm(forms.Form):
+        radio = forms.ChoiceField(widget=RadioSelect, choices=RADIO_CHOICES)
+        checkboxes = forms.MultipleChoiceField(required=False, 
+            widget=CheckboxSelectMultiple, choices=CHECKBOX_CHOICES)
+        date = forms.DateField(widget=SelectDateWidget(years=YEAR_CHOICES))
+
+
+Widgets with choices
+^^^^^^^^^^^^^^^^^^^^
+
+A couple of widgets deal with choices; these are mainly based on the 
+:class:`Select` widget and in most cases "owned" by a field based on
+:class:`ChoiceField`. The :class:`ChoiceField` dictates what the choices are 
+and resets the choices on the widget everytime they get changed on the field.
+
+Widgets which offer a ``choices`` attribute can however be used with fields
+which are not based on choice, such as a :class:`TextField`, but it is 
+recommended to use a :class:`ChoiceField`-based field when the choices are 
+inherent to the model and not just the representational widget.
+
 Customizing widget instances
 ----------------------------
 
@@ -237 +102 @@
 
 On a real Web page, you probably don't want every widget to look the same. You
 might want a larger input element for the comment, and you might want the 'name'
-widget to have some special CSS class. To do this, you use the ``attrs``
+widget to have some special CSS class. To do this, you use the :attr:`Widget.attrs`
 argument when creating the widget:
 
-.. attribute:: Widget.attrs
-
 For example::
 
     class CommentForm(forms.Form):
@@ -258 +121 @@
     <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
     <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
+
+Built-in widgets
+----------------
+
+Django provides a representation of all the basic HTML widgets, plus some
+commonly used groups of widgets:
+
+.. class:: Widget
+
+    This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.
+
+    .. attribute:: Widget.attrs
+    
+        A dictionary containing HTML attributes to be set on the rendered widget.
+
+        .. code-block:: python
+            
+            >>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
+            >>> name.render('name', 'A name')
+            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'
+
+
+.. class:: TextInput
+
+    Text input: ``<input type='text' ...>``
+
+.. class:: PasswordInput
+
+    Password input: ``<input type='password' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: PasswordInput.render_value
+
+        Determines whether the widget will have a value filled in when the
+        form is re-displayed after a validation error (default is ``False``).
+
+        .. versionchanged:: 1.3
+            The default value for
+            :attr:`~PasswordInput.render_value` was
+            changed from ``True`` to ``False``
+
+.. class:: HiddenInput
+
+    Hidden input: ``<input type='hidden' ...>``
+
+.. class:: MultipleHiddenInput
+
+    Multiple ``<input type='hidden' ...>`` widgets.
+
+    A widget that handles multiple hidden widgets for fields that have a list of values.
+
+    .. attribute:: MultipleHiddenInput.choices
+
+        This attribute is optional when the field does not have a :attr:`~Field.choices`
+        attribute. If it does, it will override anything you set here when the attribute
+        is updated on the :class:`Field`.
+
+.. class:: FileInput
+
+    File upload input: ``<input type='file' ...>``
+
+.. class:: ClearableFileInput
+
+    .. versionadded:: 1.3
+
+    File upload input: ``<input type='file' ...>``, with an additional checkbox
+    input to clear the field's value, if the field is not required and has
+    initial data.
+
+.. class:: DateInput
+
+    Date input as a simple text box: ``<input type='text' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: DateInput.format
+
+        The format in which this field's initial value will be displayed.
+
+    If no ``format`` argument is provided, the default format is the first 
+    format found in :setting:`DATE_INPUT_FORMATS`.
+
+.. class:: DateTimeInput
+
+    Date/time input as a simple text box: ``<input type='text' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: DateTimeInput.format
+
+        The format in which this field's initial value will be displayed.
+
+    If no ``format`` argument is provided, the default format is the first 
+    format found in :setting:`DATETIME_INPUT_FORMATS`.
+
+.. class:: TimeInput
+
+    Time input as a simple text box: ``<input type='text' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: TimeInput.format
+
+        The format in which this field's initial value will be displayed.
+
+    If no ``format`` argument is provided, the default format is the first 
+    format found in :setting:`TIME_INPUT_FORMATS`.
+
+.. class:: Textarea
+
+    Text area: ``<textarea>...</textarea>``
+
+.. class:: CheckboxInput
+
+    Checkbox: ``<input type='checkbox' ...>``
+
+    Takes one optional argument:
+
+    .. attribute:: CheckboxInput.check_test
+
+        A callable that takes the value of the CheckBoxInput
+        and returns ``True`` if the checkbox should be checked for
+        that value.
+
+.. class:: Select
+
+    Select widget: ``<select><option ...>...</select>``
+
+    .. attribute:: Select.choices
+
+        This attribute is optional when the field does not have a :attr:`~Field.choices`
+        attribute. If it does, it will override anything you set here when the attribute
+        is updated on the :class:`Field`.
+
+.. class:: NullBooleanSelect
+
+    Select widget with options 'Unknown', 'Yes' and 'No'
+
+.. class:: SelectMultiple
+
+    Similar to :class:`Select`, but allows multiple selection:
+    ``<select multiple='multiple'>...</select>``
+
+.. class:: RadioSelect
+
+    Similar to :class:`Select`, but rendered as a list of radio buttons:
+
+    .. code-block:: html
+
+        <ul>
+          <li><input type='radio' ...></li>
+          ...
+        </ul>
+
+.. class:: CheckboxSelectMultiple
+
+    Similar to :class:`SelectMultiple`, but rendered as a list of check buttons:
+
+    .. code-block:: html
+
+        <ul>
+          <li><input type='checkbox' ...></li>
+          ...
+        </ul>
+
+.. class:: MultiWidget
+
+    Wrapper around multiple other widgets.
+
+    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:
+
+    * 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 a string of HTML that formats them any way you'd like.
+
+    You'll probably want to use this class with :class:`MultiValueField`.
+
+    .. attribute:: widgets
+
+        An iterable containing the widgets needed.
+
+.. class:: SplitDateTimeWidget
+
+    Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput` 
+    for the date, and :class:`TimeInput` for the time.
+
+    ``SplitDateTimeWidget`` has two optional attributes:
+
+    .. attribute:: SplitDateTimeWidget.date_format
+
+        Similar to :attr:`DateInput.format`
+
+    .. attribute:: SplitDateTimeWidget.time_format
+
+        Similar to :attr:`TimeInput.format`
+
+
+.. class:: SplitHiddenDateTimeWidget
+
+    Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
+    both date and time.
+
+.. currentmodule:: django.forms.widgets.extras
+
+.. class:: SelectDateWidget
+
+    Wrapper around three :class:`~django.forms.Select` widgets: one each for month, day, and year.
+    Note that this widget lives in a separate file from the standard widgets.
+
+    Takes one optional argument:
+
+    .. attribute:: SelectDateWidget.years
+
+        An optional list/tuple of years to use in the "year" select box.
+        The default is a list containing the current year and the next 9 years.