Refs #32339 -- Doc'd setting a form's template_name is recomended over using as_* methods.

2 files changed, 18 insertions, 55 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 3a9ea81723..a9e921d347 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -554,9 +554,9 @@ This default output wraps each field with a ``<div>``. Notice the following:
   it uses boolean attributes such as ``checked`` rather than the XHTML style
   of ``checked='checked'``.
 
-Although ``<div>`` 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.
+Although ``<div>`` output is the default output style when you ``print`` a form
+you can customize the output by using your own form template which can be set
+site-wide, per-form, or per-instance. See :ref:`reusable-form-templates`.
 
 Default rendering
 -----------------
@@ -620,14 +620,20 @@ template, see also :ref:`overriding-built-in-form-templates`.
 Output styles
 -------------
 
-As well as rendering the form directly, such as in a template with
-``{{ form }}``, the following helper functions serve as a proxy to
-:meth:`Form.render` passing a particular ``template_name`` value.
+The recommended approach for changing form output style is to set a custom form
+template either site-wide, per-form, or per-instance. See
+:ref:`reusable-form-templates` for examples.
 
-These helpers are most useful in a template, where you need to override the
-form renderer or form provided value but cannot pass the additional parameter
-to :meth:`~Form.render`. For example, you can render a form as an unordered
-list using ``{{ form.as_ul }}``.
+The following helper functions are provided for backward compatibility and are
+a proxy to :meth:`Form.render` passing a particular ``template_name`` value.
+
+.. note::
+
+    Of the framework provided templates and output styles, the default
+    ``as_div()`` is recommended over the ``as_p()``, ``as_table()``, and
+    ``as_ul()`` versions as the template implements ``<fieldset>`` and
+    ``<legend>`` to group related inputs and is easier for screen reader users
+    to navigate.
 
 Each helper pairs a form method with an attribute giving the appropriate
 template name.
@@ -670,13 +676,6 @@ The template used by ``as_div()``. Default: ``'django/forms/div.html'``.
     <input type="checkbox" name="cc_myself" id="id_cc_myself">
     </div>
 
-.. note::
-
-    Of the framework provided templates and output styles, ``as_div()`` is
-    recommended over the ``as_p()``, ``as_table()``, and ``as_ul()`` versions
-    as the template implements ``<fieldset>`` and ``<legend>`` to group related
-    inputs and is easier for screen reader users to navigate.
-
 ``as_p()``
 ~~~~~~~~~~
 
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index 9ca3509266..3d409f5f06 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -493,6 +493,8 @@ appropriately.
     ``<form>`` tags, or the form's ``submit`` control. You will have to provide
     these yourself.
 
+.. _reusable-form-templates:
+
 Reusable form templates
 -----------------------
 
@@ -552,44 +554,6 @@ the :meth:`.Form.render`. Here's an example of this being used in a view::
 
 See :ref:`ref-forms-api-outputting-html` for more details.
 
-Form rendering options
-----------------------
-
-There are other output options though for the ``<label>``/``<input>`` pairs:
-
-* ``{{ form.as_div }}`` will render them wrapped in ``<div>`` tags.
-
-* ``{{ form.as_table }}`` will render them as table cells wrapped in ``<tr>``
-  tags.
-
-* ``{{ form.as_p }}`` will render them wrapped in ``<p>`` tags.
-
-* ``{{ form.as_ul }}`` will render them wrapped in ``<li>`` tags.
-
-Note that you'll have to provide the surrounding ``<table>`` or ``<ul>``
-elements yourself.
-
-Here's the output of ``{{ form.as_p }}`` for our ``ContactForm`` instance:
-
-.. code-block:: html+django
-
-    <p><label for="id_subject">Subject:</label>
-        <input id="id_subject" type="text" name="subject" maxlength="100" required></p>
-    <p><label for="id_message">Message:</label>
-        <textarea name="message" id="id_message" required></textarea></p>
-    <p><label for="id_sender">Sender:</label>
-        <input type="email" name="sender" id="id_sender" required></p>
-    <p><label for="id_cc_myself">Cc myself:</label>
-        <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>
-
-Note that each form field has an ID attribute set to ``id_<field-name>``, which
-is referenced by the accompanying label tag. This is important in ensuring that
-forms are accessible to assistive technology such as screen reader software.
-You can also :ref:`customize the way in which labels and ids are generated
-<ref-forms-api-configuring-label>`.
-
-See :ref:`ref-forms-api-outputting-html` for more on this.
-
 Rendering fields manually
 -------------------------