diff options
Diffstat (limited to 'docs/ref/forms/widgets.txt')
| -rw-r--r-- | docs/ref/forms/widgets.txt | 56 |
1 files changed, 31 insertions, 25 deletions
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 2c277f4587..8c19bf1206 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -12,16 +12,17 @@ handles the rendering of the HTML, and the extraction of data from a GET/POST dictionary that corresponds to the widget. The HTML generated by the built-in widgets uses HTML5 syntax, targeting -``<!DOCTYPE html>``. For example, it uses boolean attributes such as ``checked`` -rather than the XHTML style of ``checked='checked'``. +``<!DOCTYPE html>``. For example, it uses boolean attributes such as +``checked`` rather than the XHTML style of ``checked='checked'``. .. tip:: - Widgets should not be confused with the :doc:`form fields </ref/forms/fields>`. - Form fields deal with the logic of input validation and are used directly - in templates. Widgets deal with rendering of HTML form input elements on - the web page and extraction of raw submitted data. However, widgets do - need to be :ref:`assigned <widget-to-field>` to form fields. + Widgets should not be confused with the :doc:`form fields + </ref/forms/fields>`. Form fields deal with the logic of input validation + and are used directly in templates. Widgets deal with rendering of HTML + form input elements on the web page and extraction of raw submitted data. + However, widgets do need to be :ref:`assigned <widget-to-field>` to form + fields. .. _widget-to-field: @@ -120,7 +121,8 @@ means, for example, that all :class:`TextInput` widgets will appear the same on your web pages. There are two ways to customize widgets: :ref:`per widget instance -<styling-widget-instances>` and :ref:`per widget class <styling-widget-classes>`. +<styling-widget-instances>` and +:ref:`per widget class <styling-widget-classes>`. .. _styling-widget-instances: @@ -175,8 +177,8 @@ You can also modify a widget in the form definition:: name.widget.attrs.update({"class": "special"}) comment.widget.attrs.update(size="40") -Or if the field isn't declared directly on the form (such as model form fields), -you can use the :attr:`Form.fields` attribute:: +Or if the field isn't declared directly on the form (such as model form +fields), you can use the :attr:`Form.fields` attribute:: class CommentForm(forms.ModelForm): def __init__(self, *args, **kwargs): @@ -279,7 +281,8 @@ foundation for custom widgets. this widget is required. * ``'value'``: The value as returned by :meth:`format_value`. * ``'attrs'``: HTML attributes to be set on the rendered widget. The - combination of the :attr:`attrs` attribute and the ``attrs`` argument. + combination of the :attr:`attrs` attribute and the ``attrs`` + argument. * ``'template_name'``: The value of ``self.template_name``. ``Widget`` subclasses can provide custom context values by overriding @@ -331,8 +334,8 @@ foundation for custom widgets. An attribute to identify if the widget should be grouped in a ``<fieldset>`` with a ``<legend>`` when rendered. Defaults to ``False`` - but is ``True`` when the widget contains multiple ``<input>`` tags such as - :class:`~django.forms.CheckboxSelectMultiple`, + but is ``True`` when the widget contains multiple ``<input>`` tags such + as :class:`~django.forms.CheckboxSelectMultiple`, :class:`~django.forms.RadioSelect`, :class:`~django.forms.MultiWidget`, :class:`~django.forms.SplitDateTimeWidget`, and @@ -507,8 +510,8 @@ Built-in widgets Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in the ``django.forms.widgets`` module, -including :ref:`the input of text <text-widgets>`, :ref:`various checkboxes -and selectors <selector-widgets>`, :ref:`uploading files <file-upload-widgets>`, +including :ref:`the input of text <text-widgets>`, :ref:`various checkboxes and +selectors <selector-widgets>`, :ref:`uploading files <file-upload-widgets>`, and :ref:`handling of multi-valued input <composite-widgets>`. .. _text-widgets: @@ -637,7 +640,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. * ``template_name``: ``'django/forms/widgets/date.html'`` * Renders as: ``<input type="text" ...>`` - Takes same arguments as :class:`TextInput`, with one more optional argument: + Takes same arguments as :class:`TextInput`, with one more optional + argument: .. attribute:: DateInput.format @@ -657,7 +661,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. * ``template_name``: ``'django/forms/widgets/datetime.html'`` * Renders as: ``<input type="text" ...>`` - Takes same arguments as :class:`TextInput`, with one more optional argument: + Takes same arguments as :class:`TextInput`, with one more optional + argument: .. attribute:: DateTimeInput.format @@ -681,7 +686,8 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. * ``template_name``: ``'django/forms/widgets/time.html'`` * Renders as: ``<input type="text" ...>`` - Takes same arguments as :class:`TextInput`, with one more optional argument: + Takes same arguments as :class:`TextInput`, with one more optional + argument: .. attribute:: TimeInput.format @@ -866,9 +872,9 @@ that specifies the template used to render each choice. For example, for the The outer ``<div>`` container receives the ``id`` attribute of the widget, if defined, or :attr:`BoundField.auto_id` otherwise. - When looping over the radio buttons, the ``label`` and ``input`` tags include - ``for`` and ``id`` attributes, respectively. Each radio button has an - ``id_for_label`` attribute to output the element's ID. + When looping over the radio buttons, the ``label`` and ``input`` tags + include ``for`` and ``id`` attributes, respectively. Each radio button has + an ``id_for_label`` attribute to output the element's ID. ``CheckboxSelectMultiple`` ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1023,10 +1029,10 @@ Composite widgets list (which is ``---`` by default). You can change the text of this label with the ``empty_label`` attribute. ``empty_label`` can be a ``string``, ``list``, or ``tuple``. When a string is used, all select - boxes will each have an empty choice with this label. If ``empty_label`` - is a ``list`` or ``tuple`` of 3 string elements, the select boxes will - have their own custom label. The labels should be in this order - ``('year_label', 'month_label', 'day_label')``. + boxes will each have an empty choice with this label. If + ``empty_label`` is a ``list`` or ``tuple`` of 3 string elements, the + select boxes will have their own custom label. The labels should be in + this order ``('year_label', 'month_label', 'day_label')``. .. code-block:: python |