From 476d4d508717977101bba1a7f765653e48e88e76 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Tue, 26 Apr 2022 16:01:59 +0200 Subject: Refs #32339 -- Allowed renderer to specify default form and formset templates. Co-authored-by: David Smith --- docs/ref/forms/api.txt | 18 ++++++++++++------ docs/ref/forms/renderers.txt | 29 +++++++++++++++++++++++++++-- 2 files changed, 39 insertions(+), 8 deletions(-) (limited to 'docs/ref/forms') diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 4d3cf8997d..a6b4d11f4a 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -527,12 +527,18 @@ a form object, and each rendering method returns a string. .. 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`. +The name of the template rendered if the form is cast into a string, e.g. via +``print(form)`` or in a template via ``{{ form }}``. + +By default, a property returning the value of the renderer's +:attr:`~django.forms.renderers.BaseRenderer.form_template_name`. You may set it +as a string template name in order to override that for a particular form +class. + +.. versionchanged:: 4.1 + + In older versions ``template_name`` defaulted to the string value + ``'django/forms/default.html'``. ``template_name_label`` ----------------------- diff --git a/docs/ref/forms/renderers.txt b/docs/ref/forms/renderers.txt index 809b151516..8c0263e051 100644 --- a/docs/ref/forms/renderers.txt +++ b/docs/ref/forms/renderers.txt @@ -26,9 +26,16 @@ A custom renderer can be specified by updating the :setting:`FORM_RENDERER` setting. It defaults to ``'``:class:`django.forms.renderers.DjangoTemplates`\ ``'``. -You can also provide a custom renderer by setting the +By specifying a custom form renderer and overriding +:attr:`~.BaseRenderer.form_template_name` you can adjust the default form +markup across your project from a single place. + +You can also provide a custom renderer per-form or per-widget by setting the :attr:`.Form.default_renderer` attribute or by using the ``renderer`` argument -of :meth:`.Widget.render`. +of :meth:`.Form.render`, or :meth:`.Widget.render`. + +Matching points apply to formset rendering. See :ref:`formset-rendering` for +discussion. Use one of the :ref:`built-in template form renderers ` or implement your own. Custom renderers @@ -40,6 +47,24 @@ should return a rendered templates (as a string) or raise The base class for the built-in form renderers. + .. attribute:: form_template_name + + .. versionadded:: 4.1 + + The default name of the template to use to render a form. + + Defaults to ``"django/forms/default.html"``, which is a proxy for + ``"django/forms/table.html"``. + + .. attribute:: formset_template_name + + .. versionadded:: 4.1 + + The default name of the template to use to render a formset. + + Defaults to ``"django/forms/formsets/default.html"``, which is a proxy + for ``"django/forms/formsets/table.html"``. + .. method:: get_template(template_name) Subclasses must implement this method with the appropriate template -- cgit v1.3