mirror of
https://github.com/django/django.git
synced 2024-12-26 11:06:07 +00:00
1387b17026
Thanks timo. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11488 bcc190cf-cafb-0310-a4f2-bffc1f526a37
250 lines
7.0 KiB
Plaintext
250 lines
7.0 KiB
Plaintext
.. _ref-forms-widgets:
|
|
|
|
=======
|
|
Widgets
|
|
=======
|
|
|
|
.. module:: django.forms.widgets
|
|
:synopsis: Django's built-in form widgets.
|
|
|
|
.. currentmodule:: django.forms
|
|
|
|
A widget is Django's representation of a HTML input element. The widget
|
|
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 ``True``).
|
|
|
|
.. class:: HiddenInput
|
|
|
|
Hidden input: ``<input type='hidden' ...>``
|
|
|
|
.. class:: MultipleHiddenInput
|
|
|
|
Multiple ``<input type='hidden' ...>`` widgets.
|
|
|
|
.. class:: FileInput
|
|
|
|
File upload input: ``<input type='file' ...>``
|
|
|
|
.. class:: DateInput
|
|
|
|
.. versionadded:: 1.1
|
|
|
|
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
|
|
|
|
.. versionadded:: 1.0
|
|
|
|
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'``.
|
|
|
|
.. versionchanged:: 1.1
|
|
The ``format`` argument was not supported in Django 1.0.
|
|
|
|
.. 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``.
|
|
|
|
.. versionchanged:: 1.1
|
|
The ``date_format`` and ``time_format`` arguments were not supported in Django 1.0.
|
|
|
|
.. 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.
|
|
|
|
.. code-block:: python
|
|
|
|
from django.forms.extras.widgets import SelectDateWidget
|
|
|
|
date = forms.DateField(widget=SelectDateWidget())
|
|
|
|
Specifying widgets
|
|
------------------
|
|
|
|
.. 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 -
|
|
just use the 'widget' argument on the field definition. For example::
|
|
|
|
from django import forms
|
|
|
|
class CommentForm(forms.Form):
|
|
name = forms.CharField()
|
|
url = forms.URLField()
|
|
comment = forms.CharField(widget=forms.Textarea)
|
|
|
|
This would specify a form with a comment that uses a larger Textarea widget,
|
|
rather than the default TextInput widget.
|
|
|
|
Customizing widget instances
|
|
----------------------------
|
|
|
|
When Django renders a widget as HTML, it only renders the bare minimum
|
|
HTML - Django doesn't add a class definition, or any other widget-specific
|
|
attributes. This means that all 'TextInput' widgets will appear the same
|
|
on your web page.
|
|
|
|
If you want to make one widget look different to another, you need to
|
|
specify additional attributes for each widget. When you specify a
|
|
widget, you can provide a list of attributes that will be added to the
|
|
rendered HTML for the widget.
|
|
|
|
For example, take the following simple form::
|
|
|
|
class CommentForm(forms.Form):
|
|
name = forms.CharField()
|
|
url = forms.URLField()
|
|
comment = forms.CharField()
|
|
|
|
This form will include three default TextInput widgets, with default rendering -
|
|
no CSS class, no extra attributes. This means that the input boxes provided for
|
|
each widget will be rendered exactly the same::
|
|
|
|
>>> f = CommentForm(auto_id=False)
|
|
>>> f.as_table()
|
|
<tr><th>Name:</th><td><input type="text" name="name" /></td></tr>
|
|
<tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
|
|
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
|
|
|
|
|
|
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``
|
|
argument when creating the widget:
|
|
|
|
.. attribute:: Widget.attrs
|
|
|
|
For example::
|
|
|
|
class CommentForm(forms.Form):
|
|
name = forms.CharField(
|
|
widget=forms.TextInput(attrs={'class':'special'}))
|
|
url = forms.URLField()
|
|
comment = forms.CharField(
|
|
widget=forms.TextInput(attrs={'size':'40'}))
|
|
|
|
Django will then include the extra attributes in the rendered output::
|
|
|
|
>>> f = CommentForm(auto_id=False)
|
|
>>> f.as_table()
|
|
<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>
|