diff options
Diffstat (limited to 'docs/ref/forms')
| -rw-r--r-- | docs/ref/forms/api.txt | 204 | ||||
| -rw-r--r-- | docs/ref/forms/formsets.txt | 6 | ||||
| -rw-r--r-- | docs/ref/forms/models.txt | 18 | ||||
| -rw-r--r-- | docs/ref/forms/renderers.txt | 59 |
4 files changed, 244 insertions, 43 deletions
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 9cdbc21800..9dcfbcfb09 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -520,13 +520,41 @@ Although ``<table>`` output is the default output style when you ``print`` a form, other output styles are available. Each style is available as a method on a form object, and each rendering method returns a string. +``template_name`` +----------------- + +.. versionadded:: 4.0 + +.. attribute:: Form.template_name + +The name of a template that is going to be rendered if the form is cast into a +string, e.g. via ``print(form)`` or in a template via ``{{ form }}``. By +default this template is ``'django/forms/default.html'``, which is a proxy for +``'django/forms/table.html'``. The template can be changed per form by +overriding the ``template_name`` attribute or more generally by overriding the +default template, see also :ref:`overriding-built-in-form-templates`. + +``template_name_label`` +----------------------- + +.. versionadded:: 4.0 + +.. attribute:: Form.template_name_label + +The template used to render a field's ``<label>``, used when calling +:meth:`BoundField.label_tag`. Can be changed per form by overriding this +attribute or more generally by overriding the default template, see also +:ref:`overriding-built-in-form-templates`. + ``as_p()`` ---------- .. method:: Form.as_p() -``as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>`` -containing one field:: +``as_p()`` renders the form using the template assigned to the forms +``template_name_p`` attribute, by default this template is +``'django/forms/p.html'``. This template renders the form as a series of +``<p>`` tags, with each ``<p>`` containing one field:: >>> f = ContactForm() >>> f.as_p() @@ -542,10 +570,12 @@ containing one field:: .. method:: Form.as_ul() -``as_ul()`` renders the form as a series of ``<li>`` tags, with each -``<li>`` containing one field. It does *not* include the ``<ul>`` or -``</ul>``, so that you can specify any HTML attributes on the ``<ul>`` for -flexibility:: +``as_ul()`` renders the form using the template assigned to the forms +``template_name_ul`` attribute, by default this template is +``'django/forms/ul.html'``. This template renders the form as a series of +``<li>`` tags, with each ``<li>`` containing one field. It does *not* include +the ``<ul>`` or ``</ul>``, so that you can specify any HTML attributes on the +``<ul>`` for flexibility:: >>> f = ContactForm() >>> f.as_ul() @@ -561,9 +591,10 @@ flexibility:: .. method:: Form.as_table() -Finally, ``as_table()`` outputs the form as an HTML ``<table>``. This is -exactly the same as ``print``. In fact, when you ``print`` a form object, -it calls its ``as_table()`` method behind the scenes:: +Finally, ``as_table()`` renders the form using the template assigned to the +forms ``template_name_table`` attribute, by default this template is +``'django/forms/table.html'``. This template outputs the form as an HTML +``<table>``:: >>> f = ContactForm() >>> f.as_table() @@ -574,6 +605,37 @@ it calls its ``as_table()`` method behind the scenes:: <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr> +``get_context()`` +----------------- + +.. versionadded:: 4.0 + +.. method:: Form.get_context() + +Return context for form rendering in a template. + +The available context is: + +* ``form``: The bound form. +* ``fields``: All bound fields, except the hidden fields. +* ``hidden_fields``: All hidden bound fields. +* ``errors``: All non field related or hidden field related form errors. + +``render()`` +------------ + +.. versionadded:: 4.0 + +.. method:: Form.render(template_name=None, context=None, renderer=None) + +The render method is called by ``__str__`` as well as the +:meth:`.Form.as_table`, :meth:`.Form.as_p`, and :meth:`.Form.as_ul` methods. +All arguments are optional and default to: + +* ``template_name``: :attr:`.Form.template_name` +* ``context``: Value returned by :meth:`.Form.get_context` +* ``renderer``: Value returned by :attr:`.Form.default_renderer` + .. _ref-forms-api-styling-form-rows: Styling required or erroneous form rows @@ -834,25 +896,99 @@ method you're using:: 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 -pass that in at construction time:: +.. class:: ErrorList(initlist=None, error_class=None, renderer=None) - >>> from django.forms.utils import ErrorList - >>> class DivErrorList(ErrorList): - ... def __str__(self): - ... return self.as_divs() - ... def as_divs(self): - ... if not self: return '' - ... return '<div class="errorlist">%s</div>' % ''.join(['<div class="error">%s</div>' % e for e in self]) - >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList) - >>> f.as_p() - <div class="errorlist"><div class="error">This field is required.</div></div> - <p>Subject: <input type="text" name="subject" maxlength="100" required></p> - <p>Message: <input type="text" name="message" value="Hi there" required></p> - <div class="errorlist"><div class="error">Enter a valid email address.</div></div> - <p>Sender: <input type="email" name="sender" value="invalid email address" required></p> - <p>Cc myself: <input checked type="checkbox" name="cc_myself"></p> + By default, forms use ``django.forms.utils.ErrorList`` to format validation + errors. ``ErrorList`` is a list like object where ``initlist`` is the + list of errors. In addition this class has the following attributes and + methods. + + .. attribute:: error_class + + The CSS classes to be used when rendering the error list. Any provided + classes are added to the default ``errorlist`` class. + + .. attribute:: renderer + + .. versionadded:: 4.0 + + Specifies the :doc:`renderer <renderers>` to use for ``ErrorList``. + Defaults to ``None`` which means to use the default renderer + specified by the :setting:`FORM_RENDERER` setting. + + .. attribute:: template_name + + .. versionadded:: 4.0 + + The name of the template used when calling ``__str__`` or + :meth:`render`. By default this is + ``'django/forms/errors/list/default.html'`` which is a proxy for the + ``'ul.html'`` template. + + .. attribute:: template_name_text + + .. versionadded:: 4.0 + + The name of the template used when calling :meth:`.as_text`. By default + this is ``'django/forms/errors/list/text.html'``. This template renders + the errors as a list of bullet points. + + .. attribute:: template_name_ul + + .. versionadded:: 4.0 + + The name of the template used when calling :meth:`.as_ul`. By default + this is ``'django/forms/errors/list/ul.html'``. This template renders + the errors in ``<li>`` tags with a wrapping ``<ul>`` with the CSS + classes as defined by :attr:`.error_class`. + + .. method:: get_context() + + .. versionadded:: 4.0 + + Return context for rendering of errors in a template. + + The available context is: + + * ``errors`` : A list of the errors. + * ``error_class`` : A string of CSS classes. + + .. method:: render(template_name=None, context=None, renderer=None) + + .. versionadded:: 4.0 + + The render method is called by ``__str__`` as well as by the + :meth:`.as_ul` method. + + All arguments are optional and will default to: + + * ``template_name``: Value returned by :attr:`.template_name` + * ``context``: Value returned by :meth:`.get_context` + * ``renderer``: Value returned by :attr:`.renderer` + + .. method:: as_text() + + Renders the error list using the template defined by + :attr:`.template_name_text`. + + .. method:: as_ul() + + Renders the error list using the template defined by + :attr:`.template_name_ul`. + + If you'd like to customize the rendering of errors this can be achieved by + overriding the :attr:`.template_name` attribute or more generally by + overriding the default template, see also + :ref:`overriding-built-in-form-templates`. + +.. versionchanged:: 4.0 + + Rendering of :class:`ErrorList` was moved to the template engine. + +.. deprecated:: 4.0 + + The ability to return a ``str`` when calling the ``__str__`` method is + deprecated. Use the template engine instead which returns a ``SafeString``. More granular output ==================== @@ -1086,12 +1222,16 @@ Methods of ``BoundField`` attributes for the ``<label>`` tag. The HTML that's generated includes the form's - :attr:`~django.forms.Form.label_suffix` (a colon, by default) or, if set, the - current field's :attr:`~django.forms.Field.label_suffix`. The optional + :attr:`~django.forms.Form.label_suffix` (a colon, by default) or, if set, + the current field's :attr:`~django.forms.Field.label_suffix`. The optional ``label_suffix`` parameter allows you to override any previously set - suffix. For example, you can use an empty string to hide the label on selected - fields. If you need to do this in a template, you could write a custom - filter to allow passing parameters to ``label_tag``. + suffix. For example, you can use an empty string to hide the label on + selected fields. The label is rendered using the template specified by the + forms :attr:`.Form.template_name_label`. + + .. versionchanged:: 4.0 + + The label is now rendered using the template engine. .. method:: BoundField.value() diff --git a/docs/ref/forms/formsets.txt b/docs/ref/forms/formsets.txt index 0e281f2f59..677184df05 100644 --- a/docs/ref/forms/formsets.txt +++ b/docs/ref/forms/formsets.txt @@ -11,7 +11,7 @@ Formset API reference. For introductory material about formsets, see the ``formset_factory`` =================== -.. function:: formset_factory(form, formset=BaseFormSet, extra=1, can_order=False, can_delete=False, max_num=None, validate_max=False, min_num=None, validate_min=False, absolute_max=None, can_delete_extra=True) +.. function:: formset_factory(form, formset=BaseFormSet, extra=1, can_order=False, can_delete=False, max_num=None, validate_max=False, min_num=None, validate_min=False, absolute_max=None, can_delete_extra=True, renderer=None) Returns a ``FormSet`` class for the given ``form`` class. @@ -20,3 +20,7 @@ Formset API reference. For introductory material about formsets, see the .. versionchanged:: 3.2 The ``absolute_max`` and ``can_delete_extra`` arguments were added. + + .. versionchanged:: 4.0 + + The ``renderer`` argument was added. diff --git a/docs/ref/forms/models.txt b/docs/ref/forms/models.txt index 13ed69887e..59eac83e7d 100644 --- a/docs/ref/forms/models.txt +++ b/docs/ref/forms/models.txt @@ -52,7 +52,7 @@ Model Form API reference. For introductory material about model forms, see the ``modelformset_factory`` ======================== -.. function:: modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True) +.. function:: modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None) Returns a ``FormSet`` class for the given ``model`` class. @@ -63,9 +63,9 @@ Model Form API reference. For introductory material about model forms, see the Arguments ``formset``, ``extra``, ``can_delete``, ``can_order``, ``max_num``, ``validate_max``, ``min_num``, ``validate_min``, - ``absolute_max``, and ``can_delete_extra`` are passed through to - :func:`~django.forms.formsets.formset_factory`. See :doc:`formsets - </topics/forms/formsets>` for details. + ``absolute_max``, ``can_delete_extra``, and ``renderer`` are passed + through to :func:`~django.forms.formsets.formset_factory`. See + :doc:`formsets </topics/forms/formsets>` for details. See :ref:`model-formsets` for example usage. @@ -73,10 +73,14 @@ Model Form API reference. For introductory material about model forms, see the The ``absolute_max`` and ``can_delete_extra`` arguments were added. + .. versionchanged:: 4.0 + + The ``renderer`` argument was added. + ``inlineformset_factory`` ========================= -.. function:: inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True) +.. function:: inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None) Returns an ``InlineFormSet`` using :func:`modelformset_factory` with defaults of ``formset=``:class:`~django.forms.models.BaseInlineFormSet`, @@ -90,3 +94,7 @@ Model Form API reference. For introductory material about model forms, see the .. versionchanged:: 3.2 The ``absolute_max`` and ``can_delete_extra`` arguments were added. + + .. versionchanged:: 4.0 + + The ``renderer`` argument was added. diff --git a/docs/ref/forms/renderers.txt b/docs/ref/forms/renderers.txt index 58caa08c32..77ee33d662 100644 --- a/docs/ref/forms/renderers.txt +++ b/docs/ref/forms/renderers.txt @@ -68,11 +68,11 @@ it uses a :class:`~django.template.backends.jinja2.Jinja2` backend. Templates for the built-in widgets are located in ``django/forms/jinja2`` and installed apps can provide templates in a ``jinja2`` directory. -To use this backend, all the widgets in your project and its third-party apps -must have Jinja2 templates. Unless you provide your own Jinja2 templates for -widgets that don't have any, you can't use this renderer. For example, -:mod:`django.contrib.admin` doesn't include Jinja2 templates for its widgets -due to their usage of Django template tags. +To use this backend, all the forms and widgets in your project and its +third-party apps must have Jinja2 templates. Unless you provide your own Jinja2 +templates for widgets that don't have any, you can't use this renderer. For +example, :mod:`django.contrib.admin` doesn't include Jinja2 templates for its +widgets due to their usage of Django template tags. ``TemplatesSetting`` -------------------- @@ -97,6 +97,29 @@ Using this renderer along with the built-in widget templates requires either: Using this renderer requires you to make sure the form templates your project needs can be located. +Context available in formset templates +====================================== + +.. versionadded:: 4.0 + +Formset templates receive a context from :meth:`.BaseFormSet.get_context`. By +default, formsets receive a dictionary with the following values: + +* ``formset``: The formset instance. + +Context available in form templates +=================================== + +.. versionadded:: 4.0 + +Form templates receive a context from :meth:`.Form.get_context`. By default, +forms receive a dictionary with the following values: + +* ``form``: The bound form. +* ``fields``: All bound fields, except the hidden fields. +* ``hidden_fields``: All hidden bound fields. +* ``errors``: All non field related or hidden field related form errors. + Context available in widget templates ===================================== @@ -114,6 +137,32 @@ Some widgets add further information to the context. For instance, all widgets that subclass ``Input`` defines ``widget['type']`` and :class:`.MultiWidget` defines ``widget['subwidgets']`` for looping purposes. +.. _overriding-built-in-formset-templates: + +Overriding built-in formset templates +===================================== + +.. versionadded:: 4.0 + +:attr:`.BaseFormSet.template_name` + +To override formset templates, you must use the :class:`TemplatesSetting` +renderer. Then overriding widget templates works :doc:`the same as +</howto/overriding-templates>` overriding any other template in your project. + +.. _overriding-built-in-form-templates: + +Overriding built-in form templates +================================== + +.. versionadded:: 4.0 + +:attr:`.Form.template_name` + +To override form templates, you must use the :class:`TemplatesSetting` +renderer. Then overriding widget templates works :doc:`the same as +</howto/overriding-templates>` overriding any other template in your project. + .. _overriding-built-in-widget-templates: Overriding built-in widget templates |