diff options
Diffstat (limited to 'docs/topics/forms')
| -rw-r--r-- | docs/topics/forms/formsets.txt | 21 | ||||
| -rw-r--r-- | docs/topics/forms/index.txt | 42 |
2 files changed, 52 insertions, 11 deletions
diff --git a/docs/topics/forms/formsets.txt b/docs/topics/forms/formsets.txt index a549a047cd..0206959f1d 100644 --- a/docs/topics/forms/formsets.txt +++ b/docs/topics/forms/formsets.txt @@ -783,11 +783,22 @@ Formsets have the following attributes and methods associated with rendering: .. versionadded:: 4.0 - The name of the template used when calling ``__str__`` or :meth:`.render`. - This template renders the formset's management form and then each form in - the formset as per the template defined by the form's - :attr:`~django.forms.Form.template_name`. This is a proxy of ``as_table`` - by default. + The name of the template rendered if the formset is cast into a string, + e.g. via ``print(formset)`` or in a template via ``{{ formset }}``. + + By default, a property returning the value of the renderer's + :attr:`~django.forms.renderers.BaseRenderer.formset_template_name`. You may + set it as a string template name in order to override that for a particular + formset class. + + This template will be used to render the formset's management form, and + then each form in the formset as per the template defined by the form's + :attr:`~django.forms.Form.template_name`. + + .. versionchanged:: 4.1 + + In older versions ``template_name`` defaulted to the string value + ``'django/forms/formset/default.html'``. .. attribute:: BaseFormSet.template_name_p diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt index 2d0d61aa02..0e98e50692 100644 --- a/docs/topics/forms/index.txt +++ b/docs/topics/forms/index.txt @@ -759,10 +759,14 @@ 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 -overriding the forms :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. +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: @@ -779,16 +783,42 @@ In your templates: </div> {% endfor %} -In your form:: +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' + 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 ============== |
