#############
Template tags
#############

django-formrenderingtools provides the "form_layouts" template tag library, 
which itself provides the following template tags:

* :ref:`form`: renders a full form, with all errors (field and non field 
  errors), fields and labels.
* :ref:`form_errors`: renders global form errors, i.e. non field errors
* :ref:`field_list`: renders a list of fields, with field errors, fields and 
  labels. By default, uses {% field %}.
* :ref:`field`: renders a field, with field errors and label. By default, uses 
  {% label %}.
* :ref:`field_errors`: renders errors related to a field
* :ref:`label`: renders a field's label
* :ref:`help_text`: renders a field's help text

.. _form:

****
form
****

Renders a full form, with all errors (field and non field errors), fields and 
labels.

By default, uses :ref:`field_list`.

Minimal usage
=============

.. code-block:: django
  
  {% load form_layouts %}
  {% form %}

In this case:

* a context variable named "form" is required. You can use {% with %} for this
  purpose.
* the default layout will be used
* all fields in the form will be displayed, in the order specified in the
  form's python class definition.

Usage with options
==================

.. code-block:: django
  
  {% load form_layouts %}
  {% form form=my_form layout="my_layout" fields="a_field_name,another_field" exclude_fields="some_field_to_ignore" %}

Input parameters
================

form
    optional, a context variable, the form instance to be rendered.
    If empty, the template tag searches for a context variable named "form".

layout
    optional, defaults to settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT ("default"
    by default), a context variable or a string, the layout to be used.
    Through this parameter, you implicitely specify the template directory to 
    use. See :doc:`/reference/template_names` for details.

fields
    optional, defaults to None, a list or comma-separated (no spaces allowed)
    string which represents the names of fields that you want to be displayed.
    Only those fields will be displayed. If a field is in both "fields" and
    "exclude_fields", then it won't be displayed.

exclude_fields
    optional, defaults to None, a list or comma-separated string which 
    represents the names of fields that you do not want to be displayed. Only
    other fields will be displayed. If a field is in both "fields" and 
    "exclude_fields", then it won't be displayed.

template
    optional, defaults to "default.html", a string, the template name to use.
    See :doc:`/reference/template_names` for details.

.. _form_errors:

***********
form_errors
***********

Renders non field errors of a form.

Input parameters are the same as the :ref:`form` template tag.

.. _field_list:

**********
field_list
**********

Renders several fields.

Input parameters are the same as the :ref:`form` template tag.

.. _field:

*****
field
*****

Renders a field: errors, label, field and help_text.

Notice that Django-formrenderingtools is not intended to customize widgets.
Have a look at `django-floppyforms
<http://pypi.python.org/pypi/django-floppyforms>`_ for this purpose.

Input parameters
================

field
   optional, a context variable, the field instance to be rendered.
   If empty, the template tag searches for a context variable named "field".

layout
   optional, defaults to settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT ("default"
   by default), a context variable or a string, the layout to be used.
   Through this parameter, you implicitely specify the template directory to 
   use. See :doc:`/reference/template_names` for details.

template
    optional, defaults to "default.html", a string, the template name to use.
    See :doc:`/reference/template_names` for details.

.. _field_errors:

************
field_errors
************

Renders the errors attached to a field.

Input parameters are the same as the :ref:`field` template tag.

.. _label:

*****
label
*****

Renders the label of a field.

Input parameters are the same as the :ref:`field` template tag.

.. _help_text:

*********
help_text
*********

Renders the help text of a field.

Input parameters are the same as the :ref:`field` template tag.