diff options
Diffstat (limited to 'docs/ref/forms/api.txt')
| -rw-r--r-- | docs/ref/forms/api.txt | 128 |
1 files changed, 78 insertions, 50 deletions
diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index a6b4d11f4a..8530af2611 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -520,9 +520,15 @@ Although ``<table>`` 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,8 +546,42 @@ class. In older versions ``template_name`` defaulted to the string value ``'django/forms/default.html'``. +``render()`` +~~~~~~~~~~~~ + +.. versionadded:: 4.0 + +.. method:: Form.render(template_name=None, context=None, renderer=None) + +The render method is called by ``__str__`` as well as the +:meth:`.Form.as_table`, :meth:`.Form.as_p`, and :meth:`.Form.as_ul` methods. +All arguments are optional and default to: + +* ``template_name``: :attr:`.Form.template_name` +* ``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 @@ -552,15 +592,32 @@ The template used to render a field's ``<label>``, used when calling form by overriding this attribute or more generally by overriding the default 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. + +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 }}``. + +Each helper pairs a form method with an attribute giving the appropriate +template name. + ``as_p()`` ----------- +~~~~~~~~~~ + +.. attribute:: Form.template_name_p + +The template used by ``as_p()``. Default: ``'django/forms/p.html'``. .. method:: Form.as_p() -``as_p()`` renders the form using the template assigned to the forms -``template_name_p`` attribute, by default this template is -``'django/forms/p.html'``. This template renders the form as a series of -``<p>`` tags, with each ``<p>`` containing one field:: +``as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>`` +containing one field:: >>> f = ContactForm() >>> f.as_p() @@ -572,16 +629,17 @@ template, see also :ref:`overriding-built-in-form-templates`. <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p> ``as_ul()`` ------------ +~~~~~~~~~~~ + +.. attribute:: Form.template_name_ul + +The template used by ``as_ul()``. Default: ``'django/forms/ul.html'``. .. method:: Form.as_ul() -``as_ul()`` renders the form using the template assigned to the forms -``template_name_ul`` attribute, by default this template is -``'django/forms/ul.html'``. This template renders the form as a series of -``<li>`` tags, with each ``<li>`` containing one field. It does *not* include -the ``<ul>`` or ``</ul>``, so that you can specify any HTML attributes on the -``<ul>`` for flexibility:: +``as_ul()`` renders the form as a series of ``<li>`` tags, with each ``<li>`` +containing one field. It does *not* include the ``<ul>`` or ``</ul>``, so that +you can specify any HTML attributes on the ``<ul>`` for flexibility:: >>> f = ContactForm() >>> f.as_ul() @@ -593,14 +651,15 @@ the ``<ul>`` or ``</ul>``, so that you can specify any HTML attributes on the <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li> ``as_table()`` --------------- +~~~~~~~~~~~~~~ + +.. attribute:: Form.template_name_table + +The template used by ``as_table()``. Default: ``'django/forms/table.html'``. .. method:: Form.as_table() -Finally, ``as_table()`` renders the form using the template assigned to the -forms ``template_name_table`` attribute, by default this template is -``'django/forms/table.html'``. This template outputs the form as an HTML -``<table>``:: +``as_table()`` renders the form as an HTML ``<table>``:: >>> f = ContactForm() >>> f.as_table() @@ -611,37 +670,6 @@ forms ``template_name_table`` attribute, by default this template is <tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr> <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr> -``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 - -.. method:: Form.render(template_name=None, context=None, renderer=None) - -The render method is called by ``__str__`` as well as the -:meth:`.Form.as_table`, :meth:`.Form.as_p`, and :meth:`.Form.as_ul` methods. -All arguments are optional and default to: - -* ``template_name``: :attr:`.Form.template_name` -* ``context``: Value returned by :meth:`.Form.get_context` -* ``renderer``: Value returned by :attr:`.Form.default_renderer` - .. _ref-forms-api-styling-form-rows: Styling required or erroneous form rows |