Code

Ticket #16264: django-16264.diff

File django-16264.diff, 14.6 KB (added by bpeschier, 3 years ago)
Line 
1diff -r f7582637764c docs/ref/forms/widgets.txt
2--- a/docs/ref/forms/widgets.txt        Tue Jun 14 23:37:12 2011 +0000
3+++ b/docs/ref/forms/widgets.txt        Wed Jun 15 18:00:35 2011 +0200
4@@ -11,187 +11,15 @@
5 handles the rendering of the HTML, and the extraction of data from a GET/POST
6 dictionary that corresponds to the widget.
7 
8-Django provides a representation of all the basic HTML widgets, plus some
9-commonly used groups of widgets:
10-
11-.. class:: TextInput
12-
13-    Text input: ``<input type='text' ...>``
14-
15-.. class:: PasswordInput
16-
17-    Password input: ``<input type='password' ...>``
18-
19-    Takes one optional argument:
20-
21-    .. attribute:: PasswordInput.render_value
22-
23-        Determines whether the widget will have a value filled in when the
24-        form is re-displayed after a validation error (default is ``False``).
25-
26-.. versionchanged:: 1.3
27-    The default value for
28-    :attr:`~PasswordInput.render_value` was
29-    changed from ``True`` to ``False``
30-
31-.. class:: HiddenInput
32-
33-    Hidden input: ``<input type='hidden' ...>``
34-
35-.. class:: MultipleHiddenInput
36-
37-    Multiple ``<input type='hidden' ...>`` widgets.
38-
39-.. class:: FileInput
40-
41-    File upload input: ``<input type='file' ...>``
42-
43-.. class:: ClearableFileInput
44-
45-    .. versionadded:: 1.3
46-
47-    File upload input: ``<input type='file' ...>``, with an additional checkbox
48-    input to clear the field's value, if the field is not required and has
49-    initial data.
50-
51-.. class:: DateInput
52-
53-    Date input as a simple text box: ``<input type='text' ...>``
54-
55-    Takes one optional argument:
56-
57-    .. attribute:: DateInput.format
58-
59-        The format in which this field's initial value will be displayed.
60-
61-    If no ``format`` argument is provided, the default format is ``'%Y-%m-%d'``.
62-
63-.. class:: DateTimeInput
64-
65-    Date/time input as a simple text box: ``<input type='text' ...>``
66-
67-    Takes one optional argument:
68-
69-    .. attribute:: DateTimeInput.format
70-
71-        The format in which this field's initial value will be displayed.
72-
73-    If no ``format`` argument is provided, the default format is ``'%Y-%m-%d
74-    %H:%M:%S'``.
75-
76-.. class:: TimeInput
77-
78-    Time input as a simple text box: ``<input type='text' ...>``
79-
80-    Takes one optional argument:
81-
82-    .. attribute:: TimeInput.format
83-
84-        The format in which this field's initial value will be displayed.
85-
86-    If no ``format`` argument is provided, the default format is ``'%H:%M:%S'``.
87-
88-.. class:: Textarea
89-
90-    Text area: ``<textarea>...</textarea>``
91-
92-.. class:: CheckboxInput
93-
94-    Checkbox: ``<input type='checkbox' ...>``
95-
96-    Takes one optional argument:
97-
98-    .. attribute:: CheckboxInput.check_test
99-
100-        A callable that takes the value of the CheckBoxInput
101-        and returns ``True`` if the checkbox should be checked for
102-        that value.
103-
104-.. class:: Select
105-
106-    Select widget: ``<select><option ...>...</select>``
107-
108-    Requires that your field provides :attr:`~Field.choices`.
109-
110-.. class:: NullBooleanSelect
111-
112-    Select widget with options 'Unknown', 'Yes' and 'No'
113-
114-.. class:: SelectMultiple
115-
116-    Select widget allowing multiple selection: ``<select
117-    multiple='multiple'>...</select>``
118-
119-    Requires that your field provides :attr:`~Field.choices`.
120-
121-.. class:: RadioSelect
122-
123-    A list of radio buttons:
124-
125-    .. code-block:: html
126-
127-        <ul>
128-          <li><input type='radio' ...></li>
129-          ...
130-        </ul>
131-
132-    Requires that your field provides :attr:`~Field.choices`.
133-
134-.. class:: CheckboxSelectMultiple
135-
136-    A list of checkboxes:
137-
138-    .. code-block:: html
139-
140-        <ul>
141-          <li><input type='checkbox' ...></li>
142-          ...
143-        </ul>
144-
145-.. class:: MultiWidget
146-
147-    Wrapper around multiple other widgets
148-
149-.. class:: SplitDateTimeWidget
150-
151-    Wrapper around two widgets: ``DateInput`` for the date, and ``TimeInput``
152-    for the time.
153-
154-    Takes two optional arguments, ``date_format`` and ``time_format``, which
155-    work just like the ``format`` argument for ``DateInput`` and ``TimeInput``.
156-
157-.. currentmodule:: django.forms.extras.widgets
158-
159-.. class:: SelectDateWidget
160-
161-    Wrapper around three select widgets: one each for month, day, and year.
162-    Note that this widget lives in a separate file from the standard widgets.
163-
164-    Takes one optional argument:
165-
166-    .. attribute:: List.years
167-
168-        An optional list/tuple of years to use in the "year" select box.
169-        The default is a list containing the current year and the next 9 years.
170-
171-    .. code-block:: python
172-
173-        from django.forms.extras.widgets import SelectDateWidget
174-
175-        date = forms.DateField(widget=SelectDateWidget())
176-
177 Specifying widgets
178 ------------------
179-.. currentmodule:: django.forms
180-
181-.. attribute:: Form.widget
182 
183 Whenever you specify a field on a form, Django will use a default widget
184 that is appropriate to the type of data that is to be displayed. To find
185 which widget is used on which field, see the documentation for the
186 built-in Field classes.
187 
188-However, if you want to use a different widget for a field, you can -
189+However, if you want to use a different widget for a field, you can
190 just use the 'widget' argument on the field definition. For example::
191 
192     from django import forms
193@@ -204,6 +32,43 @@
194 This would specify a form with a comment that uses a larger Textarea widget,
195 rather than the default TextInput widget.
196 
197+
198+Setting arguments for widgets
199+-----------------------------
200+
201+Some widgets take over arguments from the fields they represent, for example
202+:class:`RadioSelect` or :class:`MultipleChoiceField` will use the choices of
203+the underlying field. Some widgets have optional extra arguments; they can be
204+set when defining the widget on the field. The reference below describes which
205+options can be set.
206+
207+In this example, the years attribute is set for a
208+:class:`django.forms.widgets.extras.SelectDateWidget`: ::
209+
210+    YEAR_CHOICES = ('2010', '2009',)
211+    RADIO_CHOICES = (('1','Radio 1',), ('2','Radio 2',),)
212+    CHECKBOX_CHOICES = (('1','The first choice',), ('2','The Second Choice',),)
213+
214+    class SimpleForm(forms.Form):
215+        radio = forms.ChoiceField(widget=RadioSelect, choices=RADIO_CHOICES)
216+        checkboxes = forms.MultipleChoiceField(required=False,
217+            widget=CheckboxSelectMultiple, choices=CHECKBOX_CHOICES)
218+        date = forms.DateField(widget=SelectDateWidget(years=YEAR_CHOICES))
219+
220+
221+Widgets with choices
222+^^^^^^^^^^^^^^^^^^^^
223+
224+A couple of widgets deal with choices; these are mainly based on the
225+:class:`Select` widget and in most cases "owned" by a field based on
226+:class:`ChoiceField`. The :class:`ChoiceField` dictates what the choices are
227+and resets the choices on the widget everytime they get changed on the field.
228+
229+Widgets which offer a ``choices`` attribute can however be used with fields
230+which are not based on choice, such as a :class:`TextField`, but it is
231+recommended to use a :class:`ChoiceField`-based field when the choices are
232+inherent to the model and not just the representational widget.
233+
234 Customizing widget instances
235 ----------------------------
236 
237@@ -237,11 +102,9 @@
238 
239 On a real Web page, you probably don't want every widget to look the same. You
240 might want a larger input element for the comment, and you might want the 'name'
241-widget to have some special CSS class. To do this, you use the ``attrs``
242+widget to have some special CSS class. To do this, you use the :attr:`Widget.attrs`
243 argument when creating the widget:
244 
245-.. attribute:: Widget.attrs
246-
247 For example::
248 
249     class CommentForm(forms.Form):
250@@ -258,3 +121,234 @@
251     <tr><th>Name:</th><td><input type="text" name="name" class="special"/></td></tr>
252     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
253     <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
254+
255+Built-in widgets
256+----------------
257+
258+Django provides a representation of all the basic HTML widgets, plus some
259+commonly used groups of widgets:
260+
261+.. class:: Widget
262+
263+    This abstract class cannot be rendered, but provides the basic attribute :attr:`~Widget.attrs`.
264+
265+    .. attribute:: Widget.attrs
266+   
267+        A dictionary containing HTML attributes to be set on the rendered widget.
268+
269+        .. code-block:: python
270+           
271+            >>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name',})
272+            >>> name.render('name', 'A name')
273+            u'<input title="Your name" type="text" name="name" value="A name" size="10" />'
274+
275+
276+.. class:: TextInput
277+
278+    Text input: ``<input type='text' ...>``
279+
280+.. class:: PasswordInput
281+
282+    Password input: ``<input type='password' ...>``
283+
284+    Takes one optional argument:
285+
286+    .. attribute:: PasswordInput.render_value
287+
288+        Determines whether the widget will have a value filled in when the
289+        form is re-displayed after a validation error (default is ``False``).
290+
291+        .. versionchanged:: 1.3
292+            The default value for
293+            :attr:`~PasswordInput.render_value` was
294+            changed from ``True`` to ``False``
295+
296+.. class:: HiddenInput
297+
298+    Hidden input: ``<input type='hidden' ...>``
299+
300+.. class:: MultipleHiddenInput
301+
302+    Multiple ``<input type='hidden' ...>`` widgets.
303+
304+    A widget that handles multiple hidden widgets for fields that have a list of values.
305+
306+    .. attribute:: MultipleHiddenInput.choices
307+
308+        This attribute is optional when the field does not have a :attr:`~Field.choices`
309+        attribute. If it does, it will override anything you set here when the attribute
310+        is updated on the :class:`Field`.
311+
312+.. class:: FileInput
313+
314+    File upload input: ``<input type='file' ...>``
315+
316+.. class:: ClearableFileInput
317+
318+    .. versionadded:: 1.3
319+
320+    File upload input: ``<input type='file' ...>``, with an additional checkbox
321+    input to clear the field's value, if the field is not required and has
322+    initial data.
323+
324+.. class:: DateInput
325+
326+    Date input as a simple text box: ``<input type='text' ...>``
327+
328+    Takes one optional argument:
329+
330+    .. attribute:: DateInput.format
331+
332+        The format in which this field's initial value will be displayed.
333+
334+    If no ``format`` argument is provided, the default format is the first
335+    format found in :setting:`DATE_INPUT_FORMATS`.
336+
337+.. class:: DateTimeInput
338+
339+    Date/time input as a simple text box: ``<input type='text' ...>``
340+
341+    Takes one optional argument:
342+
343+    .. attribute:: DateTimeInput.format
344+
345+        The format in which this field's initial value will be displayed.
346+
347+    If no ``format`` argument is provided, the default format is the first
348+    format found in :setting:`DATETIME_INPUT_FORMATS`.
349+
350+.. class:: TimeInput
351+
352+    Time input as a simple text box: ``<input type='text' ...>``
353+
354+    Takes one optional argument:
355+
356+    .. attribute:: TimeInput.format
357+
358+        The format in which this field's initial value will be displayed.
359+
360+    If no ``format`` argument is provided, the default format is the first
361+    format found in :setting:`TIME_INPUT_FORMATS`.
362+
363+.. class:: Textarea
364+
365+    Text area: ``<textarea>...</textarea>``
366+
367+.. class:: CheckboxInput
368+
369+    Checkbox: ``<input type='checkbox' ...>``
370+
371+    Takes one optional argument:
372+
373+    .. attribute:: CheckboxInput.check_test
374+
375+        A callable that takes the value of the CheckBoxInput
376+        and returns ``True`` if the checkbox should be checked for
377+        that value.
378+
379+.. class:: Select
380+
381+    Select widget: ``<select><option ...>...</select>``
382+
383+    .. attribute:: Select.choices
384+
385+        This attribute is optional when the field does not have a :attr:`~Field.choices`
386+        attribute. If it does, it will override anything you set here when the attribute
387+        is updated on the :class:`Field`.
388+
389+.. class:: NullBooleanSelect
390+
391+    Select widget with options 'Unknown', 'Yes' and 'No'
392+
393+.. class:: SelectMultiple
394+
395+    Similar to :class:`Select`, but allows multiple selection:
396+    ``<select multiple='multiple'>...</select>``
397+
398+.. class:: RadioSelect
399+
400+    Similar to :class:`Select`, but rendered as a list of radio buttons:
401+
402+    .. code-block:: html
403+
404+        <ul>
405+          <li><input type='radio' ...></li>
406+          ...
407+        </ul>
408+
409+.. class:: CheckboxSelectMultiple
410+
411+    Similar to :class:`SelectMultiple`, but rendered as a list of check buttons:
412+
413+    .. code-block:: html
414+
415+        <ul>
416+          <li><input type='checkbox' ...></li>
417+          ...
418+        </ul>
419+
420+.. class:: MultiWidget
421+
422+    Wrapper around multiple other widgets.
423+
424+    Its ``render`` method is different than other widgets', because it has to
425+    figure out how to split a single value for display in multiple widgets.
426+    The ``value`` argument can be one of two things:
427+
428+    * A list.
429+    * A normal value (e.g., a string) that has been "compressed" from
430+      a list of values.
431+
432+    In the second case -- i.e., if the value is NOT a list -- render() will
433+    first "decompress" the value into a list before rendering it. It does so by
434+    calling the decompress() method, which MultiWidget subclasses must
435+    implement. This method takes a single "compressed" value and returns a
436+    list.
437+
438+    When render() does its HTML rendering, each value in the list is rendered
439+    with the corresponding widget -- the first value is rendered in the first
440+    widget, the second value is rendered in the second widget, etc.
441+
442+    Subclasses may implement format_output(), which takes the list of rendered
443+    widgets and returns a string of HTML that formats them any way you'd like.
444+
445+    You'll probably want to use this class with :class:`MultiValueField`.
446+
447+    .. attribute:: widgets
448+
449+        An iterable containing the widgets needed.
450+
451+.. class:: SplitDateTimeWidget
452+
453+    Wrapper (using :class:`MultiWidget`) around two widgets: :class:`DateInput`
454+    for the date, and :class:`TimeInput` for the time.
455+
456+    ``SplitDateTimeWidget`` has two optional attributes:
457+
458+    .. attribute:: SplitDateTimeWidget.date_format
459+
460+        Similar to :attr:`DateInput.format`
461+
462+    .. attribute:: SplitDateTimeWidget.time_format
463+
464+        Similar to :attr:`TimeInput.format`
465+
466+
467+.. class:: SplitHiddenDateTimeWidget
468+
469+    Similar to :class:`SplitDateTimeWidget`, but uses :class:`HiddenInput` for
470+    both date and time.
471+
472+.. currentmodule:: django.forms.widgets.extras
473+
474+.. class:: SelectDateWidget
475+
476+    Wrapper around three :class:`~django.forms.Select` widgets: one each for month, day, and year.
477+    Note that this widget lives in a separate file from the standard widgets.
478+
479+    Takes one optional argument:
480+
481+    .. attribute:: SelectDateWidget.years
482+
483+        An optional list/tuple of years to use in the "year" select box.
484+        The default is a list containing the current year and the next 9 years.