diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index a6b4d11f4ad..8530af2611b 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -520,9 +520,15 @@ Although ```` 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`` +Default rendering ----------------- +The default rendering when you ``print`` a form uses the following methods and +attributes. + +``template_name`` +~~~~~~~~~~~~~~~~~ + .. versionadded:: 4.0 .. attribute:: Form.template_name @@ -540,95 +546,8 @@ class. In older versions ``template_name`` defaulted to the string value ``'django/forms/default.html'``. -``template_name_label`` ------------------------ - -.. versionadded:: 4.0 - -.. attribute:: Form.template_name_label - -The template used to render a field's ``
``:: - - >>> f = ContactForm() - >>> f.as_table() - '\n\n\n' - >>> print(f) - - - - - -``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 @@ -642,6 +561,115 @@ All arguments are optional and default to: * ``context``: Value returned by :meth:`.Form.get_context` * ``renderer``: Value returned by :attr:`.Form.default_renderer` +By passing ``template_name`` you can customize the template used for just a +single call. + +``get_context()`` +~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.0 + +.. method:: Form.get_context() + +Return the template context for rendering the form. + +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. + +``template_name_label`` +~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.0 + +.. attribute:: Form.template_name_label + +The template used to render a field's ``
``:: + + >>> f = ContactForm() + >>> f.as_table() + '\n\n\n' + >>> print(f) + + + + + .. _ref-forms-api-styling-form-rows: Styling required or erroneous form rows diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index e7709834c2f..c8e43389a0d 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -487,15 +487,83 @@ instance into the template context. So if your form is called ``form`` in the context, ``{{ form }}`` will render its ```` @@ -754,71 +822,6 @@ error in a hidden field is a sign of form tampering, since normal form interaction won't alter them. However, you could easily insert some error displays for those form errors, as well. -Reusable form templates ------------------------ - -If your site uses the same rendering logic for forms in multiple places, you -can reduce duplication by saving the form's loop in a standalone template and -setting a custom :setting:`FORM_RENDERER` to use that -:attr:`~django.forms.renderers.BaseRenderer.form_template_name` site-wide. You -can also customize per-form by overriding the form's -:attr:`~django.forms.Form.template_name` attribute to render the form using the -custom template. - -The below example will result in ``{{ form }}`` being rendered as the output of -the ``form_snippet.html`` template. - -In your templates: - -.. code-block:: html+django - - # In your template: - {{ form }} - - # In form_snippet.html: - {% for field in form %} -
- {{ field.errors }} - {{ field.label_tag }} {{ field }} -
- {% endfor %} - -Then you can configure the :setting:`FORM_RENDERER` setting: - -.. code-block:: python - :caption: settings.py - - from django.forms.renderers import TemplatesSetting - - class CustomFormRenderer(TemplatesSetting): - form_template_name = "form_snippet.html" - - FORM_RENDERER = "project.settings.CustomFormRenderer" - -… or for a single form:: - - class MyForm(forms.Form): - template_name = "form_snippet.html" - ... - -… or for a single render of a form instance, passing in the template name to -the :meth:`.Form.render()`. Here's an example of this being used in a view:: - - def index(request): - form = MyForm() - rendered_form = form.render("form_snippet.html") - context = {'form': rendered_form} - return render(request, 'index.html', context) - -.. versionchanged:: 4.0 - - Template rendering of forms was added. - -.. versionchanged:: 4.1 - - The ability to set the default ``form_template_name`` on the form renderer - was added. - Further topics ==============