Refs #32339 -- Allowed renderer to specify default form and formset templates.

Co-authored-by: David Smith <smithdc@gmail.com>

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
 ==============