diff options
Diffstat (limited to 'docs/ref/forms')
| -rw-r--r-- | docs/ref/forms/api.txt | 48 | ||||
| -rw-r--r-- | docs/ref/forms/fields.txt | 96 | ||||
| -rw-r--r-- | docs/ref/forms/formsets.txt | 2 | ||||
| -rw-r--r-- | docs/ref/forms/models.txt | 4 | ||||
| -rw-r--r-- | docs/ref/forms/validation.txt | 21 | ||||
| -rw-r--r-- | docs/ref/forms/widgets.txt | 41 |
6 files changed, 107 insertions, 105 deletions
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index c36f19ca2b..631fe1ea54 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -13,7 +13,7 @@ The Forms API .. _ref-forms-api-bound-unbound: Bound and unbound forms ------------------------ +======================= A :class:`Form` instance is either **bound** to a set of data, or **unbound**. @@ -69,7 +69,7 @@ another :class:`Form` instance. There is no way to change data in a should consider its data immutable, whether it has data or not. Using forms to validate data ----------------------------- +============================ .. method:: Form.clean() @@ -201,7 +201,7 @@ This includes ``ValidationError``\s that are raised in :meth:`Form.clean() "...") <django.forms.Form.add_error>`. Behavior of unbound forms -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- It's meaningless to validate a form with no data, but, for the record, here's what happens with unbound forms:: @@ -213,7 +213,7 @@ what happens with unbound forms:: {} Dynamic initial values ----------------------- +====================== .. attribute:: Form.initial @@ -249,7 +249,7 @@ precedence:: <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> Checking which form data has changed ------------------------------------- +==================================== .. method:: Form.has_changed() @@ -286,7 +286,7 @@ provided in :attr:`~Form.initial`. It returns an empty list if no data differs. ... print("The following fields changed: %s" % ", ".join(f.changed_data)) Accessing the fields from the form ----------------------------------- +================================== .. attribute:: Form.fields @@ -320,7 +320,7 @@ process:: '<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>' Accessing "clean" data ----------------------- +====================== .. attribute:: Form.cleaned_data @@ -414,7 +414,7 @@ fields). More information about this is in :doc:`/ref/forms/validation`. .. _ref-forms-api-outputting-html: Outputting forms as HTML ------------------------- +======================== The second task of a ``Form`` object is to render itself as HTML. To do so, simply ``print`` it:: @@ -476,7 +476,7 @@ form, other output styles are available. Each style is available as a method on a form object, and each rendering method returns a Unicode object. ``as_p()`` -~~~~~~~~~~ +---------- .. method:: Form.as_p() @@ -493,7 +493,7 @@ containing one field:: <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p> ``as_ul()`` -~~~~~~~~~~~ +----------- .. method:: Form.as_ul() @@ -512,7 +512,7 @@ flexibility:: <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li> ``as_table()`` -~~~~~~~~~~~~~~ +-------------- .. method:: Form.as_table() @@ -532,7 +532,7 @@ it calls its ``as_table()`` method behind the scenes:: .. _ref-forms-api-styling-form-rows: Styling required or erroneous form rows -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- .. attribute:: Form.error_css_class .. attribute:: Form.required_css_class @@ -571,7 +571,7 @@ classes, as needed. The HTML will look something like:: .. _ref-forms-api-configuring-label: Configuring form elements' HTML ``id`` attributes and ``<label>`` tags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------------------------------------- .. attribute:: Form.auto_id @@ -693,7 +693,7 @@ using the ``label_suffix`` parameter to :meth:`~django.forms.BoundField.label_tag`. Notes on field ordering -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are displayed in the order in which you define them in your form class. For @@ -727,7 +727,7 @@ You may rearrange the fields any time using ``order_fields()`` with a list of field names as in :attr:`~django.forms.Form.field_order`. How errors are displayed -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ If you render a bound ``Form`` object, the act of rendering will automatically run the form's validation if it hasn't already happened, and the HTML output @@ -761,7 +761,7 @@ method you're using:: .. _ref-forms-error-list-format: Customizing the error list format -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- By default, forms use ``django.forms.utils.ErrorList`` to format validation errors. If you'd like to use an alternate class for displaying errors, you can @@ -785,7 +785,7 @@ Python 2):: <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p> More granular output --------------------- +==================== The ``as_p()``, ``as_ul()``, and ``as_table()`` methods are simply shortcuts -- they're not the only way a form object can be displayed. @@ -824,7 +824,7 @@ The field-specific output honors the form object's ``auto_id`` setting:: <input type="text" name="message" id="id_message" /> Attributes of ``BoundField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. attribute:: BoundField.data @@ -922,7 +922,7 @@ Attributes of ``BoundField`` message Methods of ``BoundField`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. method:: BoundField.as_hidden(attrs=None, **kwargs) @@ -995,7 +995,7 @@ Methods of ``BoundField`` hi Customizing ``BoundField`` --------------------------- +========================== .. versionadded:: 1.9 @@ -1039,7 +1039,7 @@ Now you can access the country in a template with .. _binding-uploaded-files: Binding uploaded files to a form --------------------------------- +================================ Dealing with forms that have ``FileField`` and ``ImageField`` fields is a little more complicated than a normal form. @@ -1080,7 +1080,7 @@ form data *and* file data:: >>> f = ContactFormWithMugshot() Testing for multipart forms -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- .. method:: Form.is_multipart() @@ -1103,7 +1103,7 @@ Here's an example of how you might use this in a template:: </form> Subclassing forms ------------------ +================= If you have multiple ``Form`` classes that share fields, you can use subclassing to remove redundancy. @@ -1164,7 +1164,7 @@ by setting the name of the field to ``None`` on the subclass. For example:: .. _form-prefix: Prefixes for forms ------------------- +================== .. attribute:: Form.prefix diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 99572497ca..38803df0f8 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -33,14 +33,14 @@ exception or returns the clean value:: .. _core-field-arguments: Core field arguments --------------------- +==================== Each ``Field`` class constructor takes at least these arguments. Some ``Field`` classes take additional, field-specific arguments, but the following should *always* be accepted: ``required`` -~~~~~~~~~~~~ +------------ .. attribute:: Field.required @@ -93,7 +93,7 @@ For other ``Field`` classes, it might be ``None``. (This varies from field to field.) ``label`` -~~~~~~~~~ +--------- .. attribute:: Field.label @@ -120,7 +120,7 @@ We've specified ``auto_id=False`` to simplify the output:: <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr> ``label_suffix`` -~~~~~~~~~~~~~~~~ +---------------- .. attribute:: Field.label_suffix @@ -138,7 +138,7 @@ The ``label_suffix`` argument lets you override the form's <p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p> ``initial`` -~~~~~~~~~~~ +----------- .. attribute:: Field.initial @@ -206,7 +206,7 @@ Instead of a constant, you can also pass any callable:: The callable will be evaluated only when the unbound form is displayed, not when it is defined. ``widget`` -~~~~~~~~~~ +---------- .. attribute:: Field.widget @@ -214,7 +214,7 @@ The ``widget`` argument lets you specify a ``Widget`` class to use when rendering this ``Field``. See :doc:`/ref/forms/widgets` for more information. ``help_text`` -~~~~~~~~~~~~~ +------------- .. attribute:: Field.help_text @@ -253,7 +253,7 @@ fields. We've specified ``auto_id=False`` to simplify the output:: <p>Cc myself: <input type="checkbox" name="cc_myself" /></p> ``error_messages`` -~~~~~~~~~~~~~~~~~~ +------------------ .. attribute:: Field.error_messages @@ -280,7 +280,7 @@ In the `built-in Field classes`_ section below, each ``Field`` defines the error message keys it uses. ``validators`` -~~~~~~~~~~~~~~ +-------------- .. attribute:: Field.validators @@ -290,18 +290,18 @@ for this field. See the :doc:`validators documentation </ref/validators>` for more information. ``localize`` -~~~~~~~~~~~~ +------------ .. attribute:: Field.localize The ``localize`` argument enables the localization of form data input, as well as the rendered output. -See the :ref:`format localization <format-localization>` documentation for +See the :doc:`format localization </topics/i18n/formatting>` documentation for more information. ``disabled`` -~~~~~~~~~~~~ +------------ .. attribute:: Field.disabled @@ -313,10 +313,10 @@ Even if a user tampers with the field's value submitted to the server, it will be ignored in favor of the value from the form's initial data. Checking if the field data has changed --------------------------------------- +====================================== ``has_changed()`` -~~~~~~~~~~~~~~~~~~ +----------------- .. method:: Field.has_changed() @@ -328,7 +328,7 @@ See the :class:`Form.has_changed()` documentation for more information. .. _built-in-fields: Built-in ``Field`` classes --------------------------- +========================== Naturally, the ``forms`` library comes with a set of ``Field`` classes that represent common validation needs. This section documents each built-in field. @@ -338,7 +338,7 @@ For each field, we describe the default widget used if you don't specify (see the section on ``required`` above to understand what that means). ``BooleanField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: BooleanField(**kwargs) @@ -358,7 +358,7 @@ For each field, we describe the default widget used if you don't specify creating the ``BooleanField``. ``CharField`` -~~~~~~~~~~~~~ +------------- .. class:: CharField(**kwargs) @@ -385,7 +385,7 @@ For each field, we describe the default widget used if you don't specify trailing whitespace. ``ChoiceField`` -~~~~~~~~~~~~~~~ +--------------- .. class:: ChoiceField(**kwargs) @@ -410,7 +410,7 @@ For each field, we describe the default widget used if you don't specify callable, it is evaluated each time the field's form is initialized. ``TypedChoiceField`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. class:: TypedChoiceField(**kwargs) @@ -442,7 +442,7 @@ For each field, we describe the default widget used if you don't specify accordingly. ``DateField`` -~~~~~~~~~~~~~ +------------- .. class:: DateField(**kwargs) @@ -478,10 +478,10 @@ For each field, we describe the default widget used if you don't specify '%d %B %Y', # '25 October 2006' '%d %B, %Y'] # '25 October, 2006' - See also :ref:`format localization <format-localization>`. + See also :doc:`format localization </topics/i18n/formatting>`. ``DateTimeField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: DateTimeField(**kwargs) @@ -511,10 +511,10 @@ For each field, we describe the default widget used if you don't specify '%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y'] # '10/25/06' - See also :ref:`format localization <format-localization>`. + See also :doc:`format localization </topics/i18n/formatting>`. ``DecimalField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: DecimalField(**kwargs) @@ -552,7 +552,7 @@ For each field, we describe the default widget used if you don't specify The maximum number of decimal places permitted. ``DurationField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: DurationField(**kwargs) @@ -567,7 +567,7 @@ For each field, we describe the default widget used if you don't specify :func:`~django.utils.dateparse.parse_duration`. ``EmailField`` -~~~~~~~~~~~~~~ +-------------- .. class:: EmailField(**kwargs) @@ -583,7 +583,7 @@ For each field, we describe the default widget used if you don't specify given length. ``FileField`` -~~~~~~~~~~~~~ +------------- .. class:: FileField(**kwargs) @@ -611,7 +611,7 @@ For each field, we describe the default widget used if you don't specify length and ``%(length)d`` will be replaced with the current filename length. ``FilePathField`` -~~~~~~~~~~~~~~~~~ +----------------- .. class:: FilePathField(**kwargs) @@ -654,7 +654,7 @@ For each field, we describe the default widget used if you don't specify ``FloatField`` -~~~~~~~~~~~~~~ +-------------- .. class:: FloatField(**kwargs) @@ -671,7 +671,7 @@ For each field, we describe the default widget used if you don't specify These control the range of values permitted in the field. ``ImageField`` -~~~~~~~~~~~~~~ +-------------- .. class:: ImageField(**kwargs) @@ -703,7 +703,7 @@ For each field, we describe the default widget used if you don't specify .. _Image: https://pillow.readthedocs.org/en/latest/reference/Image.html ``IntegerField`` -~~~~~~~~~~~~~~~~ +---------------- .. class:: IntegerField(**kwargs) @@ -727,7 +727,7 @@ For each field, we describe the default widget used if you don't specify These control the range of values permitted in the field. ``GenericIPAddressField`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. class:: GenericIPAddressField(**kwargs) @@ -762,7 +762,7 @@ For each field, we describe the default widget used if you don't specify when ``protocol`` is set to ``'both'``. ``MultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- .. class:: MultipleChoiceField(**kwargs) @@ -779,7 +779,7 @@ For each field, we describe the default widget used if you don't specify Takes one extra required argument, ``choices``, as for :class:`ChoiceField`. ``TypedMultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. class:: TypedMultipleChoiceField(**kwargs) @@ -801,7 +801,7 @@ For each field, we describe the default widget used if you don't specify :class:`TypedChoiceField`. ``NullBooleanField`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. class:: NullBooleanField(**kwargs) @@ -811,7 +811,7 @@ For each field, we describe the default widget used if you don't specify * Validates nothing (i.e., it never raises a ``ValidationError``). ``RegexField`` -~~~~~~~~~~~~~~ +-------------- .. class:: RegexField(**kwargs) @@ -840,7 +840,7 @@ For each field, we describe the default widget used if you don't specify regex validation. ``SlugField`` -~~~~~~~~~~~~~ +------------- .. class:: SlugField(**kwargs) @@ -864,7 +864,7 @@ For each field, we describe the default widget used if you don't specify to ASCII letters. Defaults to ``False``. ``TimeField`` -~~~~~~~~~~~~~ +------------- .. class:: TimeField(**kwargs) @@ -888,7 +888,7 @@ For each field, we describe the default widget used if you don't specify '%H:%M', # '14:30' ``URLField`` -~~~~~~~~~~~~ +------------ .. class:: URLField(**kwargs) @@ -906,7 +906,7 @@ For each field, we describe the default widget used if you don't specify These are the same as ``CharField.max_length`` and ``CharField.min_length``. ``UUIDField`` -~~~~~~~~~~~~~ +------------- .. class:: UUIDField(**kwargs) @@ -919,10 +919,10 @@ For each field, we describe the default widget used if you don't specify to the :class:`~python:uuid.UUID` constructor. Slightly complex built-in ``Field`` classes -------------------------------------------- +=========================================== ``ComboField`` -~~~~~~~~~~~~~~ +-------------- .. class:: ComboField(**kwargs) @@ -950,7 +950,7 @@ Slightly complex built-in ``Field`` classes ValidationError: ['Ensure this value has at most 20 characters (it has 28).'] ``MultiValueField`` -~~~~~~~~~~~~~~~~~~~ +------------------- .. class:: MultiValueField(fields=(), **kwargs) @@ -1033,7 +1033,7 @@ Slightly complex built-in ``Field`` classes This method must be implemented in the subclasses. ``SplitDateTimeField`` -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- .. class:: SplitDateTimeField(**kwargs) @@ -1064,7 +1064,7 @@ Slightly complex built-in ``Field`` classes for :class:`TimeField` are used. Fields which handle relationships ---------------------------------- +================================= Two fields are available for representing relationships between models: :class:`ModelChoiceField` and @@ -1087,7 +1087,7 @@ method:: self.fields['foo_select'].queryset = ... ``ModelChoiceField`` -~~~~~~~~~~~~~~~~~~~~ +-------------------- .. class:: ModelChoiceField(**kwargs) @@ -1180,7 +1180,7 @@ method:: return "My Object #%i" % obj.id ``ModelMultipleChoiceField`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- .. class:: ModelMultipleChoiceField(**kwargs) @@ -1208,7 +1208,7 @@ method:: user's selection. Creating custom fields ----------------------- +====================== If the built-in ``Field`` classes don't meet your needs, you can easily create custom ``Field`` classes. To do this, just create a subclass of diff --git a/docs/ref/forms/formsets.txt b/docs/ref/forms/formsets.txt index 704a9bb198..144140c62e 100644 --- a/docs/ref/forms/formsets.txt +++ b/docs/ref/forms/formsets.txt @@ -12,4 +12,4 @@ Formset API reference. For introductory material about formsets, see the Returns a ``FormSet`` class for the given ``form`` class. - See :ref:`formsets` for example usage. + See :doc:`formsets </topics/forms/formsets>` for example usage. diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt index 18ada3c776..b02cf9f1bd 100644 --- a/docs/ref/forms/models.txt +++ b/docs/ref/forms/models.txt @@ -61,8 +61,8 @@ Model Form API reference. For introductory material about model forms, see the Arguments ``formset``, ``extra``, ``max_num``, ``can_order``, ``can_delete`` and ``validate_max`` are passed through to - :func:`~django.forms.formsets.formset_factory`. See :ref:`formsets` for - details. + :func:`~django.forms.formsets.formset_factory`. See :doc:`formsets + </topics/forms/formsets>` for details. See :ref:`model-formsets` for example usage. diff --git a/docs/ref/forms/validation.txt b/docs/ref/forms/validation.txt index 7f334f4361..bb9a928c1a 100644 --- a/docs/ref/forms/validation.txt +++ b/docs/ref/forms/validation.txt @@ -1,10 +1,9 @@ -.. currentmodule:: django.forms - -.. _form-and-field-validation: - +========================= Form and field validation ========================= +.. currentmodule:: django.forms + Form validation happens when the data is cleaned. If you want to customize this process, there are various places to make changes, each one serving a different purpose. Three types of cleaning methods are run during form @@ -112,7 +111,7 @@ for all remaining fields are still executed. .. _raising-validation-error: Raising ``ValidationError`` ---------------------------- +=========================== In order to make error messages flexible and easy to override, consider the following guidelines: @@ -184,7 +183,7 @@ greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name and a ``params`` dictionary). Raising multiple errors -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- If you detect multiple errors during a cleaning method and wish to signal all of them to the form submitter, it is possible to pass a list of errors to the @@ -206,7 +205,7 @@ with ``code``\s and ``params`` but a list of strings will also work:: ]) Using validation in practice ----------------------------- +============================ The previous sections explained how validation works in general for forms. Since it can sometimes be easier to put things into place by seeing each @@ -216,7 +215,7 @@ previous features. .. _validators: Using validators -~~~~~~~~~~~~~~~~ +---------------- Django's form (and model) fields support use of simple utility functions and classes known as validators. A validator is merely a callable object or @@ -254,7 +253,7 @@ argument being the pattern: ``^[-a-zA-Z0-9_]+$``. See the section on available and for an example of how to write a validator. Form field default cleaning -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- Let's first create a custom form field that validates its input is a string containing comma-separated email addresses. The full class looks like this:: @@ -300,7 +299,7 @@ method will be run as part of the cleaning process and it will, in turn, call the custom ``to_python()`` and ``validate()`` methods. Cleaning a specific field attribute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------- Continuing on from the previous example, suppose that in our ``ContactForm``, we want to make sure that the ``recipients`` field always contains the address @@ -326,7 +325,7 @@ write a cleaning method that operates on the ``recipients`` field, like so:: .. _validating-fields-with-clean: Cleaning and validating fields that depend on each other -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------------- Suppose we add another requirement to our contact form: if the ``cc_myself`` field is ``True``, the ``subject`` must contain the word ``"help"``. We are diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt index 092173cc7a..2d7a0f031d 100644 --- a/docs/ref/forms/widgets.txt +++ b/docs/ref/forms/widgets.txt @@ -22,7 +22,7 @@ dictionary that corresponds to the widget. .. _widget-to-field: Specifying widgets ------------------- +================== 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 @@ -43,9 +43,8 @@ example:: This would specify a form with a comment that uses a larger :class:`Textarea` widget, rather than the default :class:`TextInput` widget. - Setting arguments for widgets ------------------------------ +============================= Many widgets have optional extra arguments; they can be set when defining the widget on the field. In the following example, the @@ -69,9 +68,8 @@ widget on the field. In the following example, the See the :ref:`built-in widgets` for more information about which widgets are available and which arguments they accept. - Widgets inheriting from the Select widget ------------------------------------------ +========================================= Widgets inheriting from the :class:`Select` widget deal with choices. They present the user with a list of options to choose from. The different widgets @@ -96,14 +94,13 @@ example:: >>> choice_field.widget.choices [('1', 'First and only')] - Widgets which offer a :attr:`~Select.choices` attribute can however be used with fields which are not based on choice -- such as a :class:`CharField` -- 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 ----------------------------- +============================ When Django renders a widget as HTML, it only renders very minimal markup - Django doesn't add class names, or any other widget-specific attributes. This @@ -116,7 +113,7 @@ There are two ways to customize widgets: :ref:`per widget instance .. _styling-widget-instances: Styling widget instances -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ If you want to make one widget instance look different from another, you will need to specify additional attributes at the time when the widget object is @@ -167,7 +164,7 @@ You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See .. _styling-widget-classes: Styling widget classes -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- With widgets, it is possible to add assets (``css`` and ``javascript``) and more deeply customize their appearance and behavior. @@ -181,13 +178,16 @@ detail in the :doc:`Form Assets </topics/forms/media>` topic guide. .. _base-widget-classes: -Base Widget classes -------------------- +Base widget classes +=================== Base widget classes :class:`Widget` and :class:`MultiWidget` are subclassed by all the :ref:`built-in widgets <built-in widgets>` and may serve as a foundation for custom widgets. +``Widget`` +---------- + .. class:: Widget(attrs=None) This abstract class cannot be rendered, but provides the basic attribute @@ -257,6 +257,9 @@ foundation for custom widgets. customize it and add expensive processing, you should implement some caching mechanism yourself. +``MultiWidget`` +--------------- + .. class:: MultiWidget(widgets, attrs=None) A widget that is composed of multiple widgets. @@ -410,7 +413,7 @@ foundation for custom widgets. .. _built-in widgets: 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, @@ -421,7 +424,7 @@ and :ref:`handling of multi-valued input <composite-widgets>`. .. _text-widgets: Widgets handling input of text -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------ These widgets make use of the HTML elements ``input`` and ``textarea``. @@ -496,7 +499,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. If no ``format`` argument is provided, the default format is the first format found in :setting:`DATE_INPUT_FORMATS` and respects - :ref:`format-localization`. + :doc:`/topics/i18n/formatting`. ``DateTimeInput`` ~~~~~~~~~~~~~~~~~ @@ -513,7 +516,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. If no ``format`` argument is provided, the default format is the first format found in :setting:`DATETIME_INPUT_FORMATS` and respects - :ref:`format-localization`. + :doc:`/topics/i18n/formatting`. By default, the microseconds part of the time value is always set to ``0``. If microseconds are required, use a subclass with the @@ -534,7 +537,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. If no ``format`` argument is provided, the default format is the first format found in :setting:`TIME_INPUT_FORMATS` and respects - :ref:`format-localization`. + :doc:`/topics/i18n/formatting`. For the treatment of microseconds, see :class:`DateTimeInput`. @@ -548,7 +551,7 @@ These widgets make use of the HTML elements ``input`` and ``textarea``. .. _selector-widgets: Selector and checkbox widgets -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- ``CheckboxInput`` ~~~~~~~~~~~~~~~~~ @@ -712,7 +715,7 @@ When looping over the checkboxes, the ``label`` and ``input`` tags include .. _file-upload-widgets: File upload widgets -^^^^^^^^^^^^^^^^^^^ +------------------- ``FileInput`` ~~~~~~~~~~~~~ @@ -733,7 +736,7 @@ File upload widgets .. _composite-widgets: Composite widgets -^^^^^^^^^^^^^^^^^ +----------------- ``MultipleHiddenInput`` ~~~~~~~~~~~~~~~~~~~~~~~ |