######################################
Template names and directory structure
######################################

As introduced in the previous chapter, the "form_layouts" template tag library 
lets you customize several levels of form rendering. The template tag library 
searches for templates in a particular directory structure.

********
Overview
********

The default structure provided by Django-formrenderingtools is:

* templates => a template directory, included in settings.TEMPLATE_DIRS

  * form_layouts => a directory for the form_layouts material

    * default => the default layout
      
      * field => templates for fields
      * field_errors
      * field_list
      * form
      * form_errors
      * help_text
      * label

Every element in the list above is a folder. It contains one default.html 
template.

If you look at the templates provided by formrenderingtools, you will notice
that "templates/form_layouts" also contains the following folders:

* as_ul => a layout that reproduces {{ form.as_ul }}
* as_p => a layout that reproduces {{ form.as_p }}
* as_table => a layout that reproduces {{ form.as_table }}

These layouts exist for demonstration and migration purposes. They are based 
on the default layout. You can read the template code to create your own 
layouts.

***************************
How to use other templates?
***************************

Several parameters allow you to change the locations where template selection
occurs:

* the "layout" parameter of the tags in the "form_layouts" template tag 
  library. You can use whatever you want provided it is a valid directory name,
  without leading and trailing slashes:
  
  .. code-block:: django
    
    {% form layout="contact_form" %}
    {% form layout="user_account/register" %}
  
  **The "layout" parameter affects nested elements**. It means that using 
  {% form layout="contact" %} will generate implicit 
  {% field layout="contact" %} calls.

* the "template" parameter of the tags in the "form_layouts" template tag 
  library. You can use whatever you want provided it is a valid file name.
  Do not forget the extension:
  
  .. code-block:: django
    
    {% form template="contact_form.html" %}
    {% form template="user/register.html" %}
  
  **The "template" parameter affects only the current element**. It means that 
  using {% form template="contact.html" %} will generate implicit calls with 
  default template, as {% field template="default.html" %}.

********
Priority
********

As an example, if you didn't change the default template and layout names,
{% form layout='LAYOUT/DIR' template="TEMPLATE/NAME.html" %} will use the
first existing template in the following list:

* form_layouts/LAYOUT/DIR/form/TEMPLATE/NAME.html
* form_layouts/default/form/TEMPLATE/NAME.html
* form_layouts/LAYOUT/DIR/form/default.html
* form_layouts/default/form/default.html

Similar rules are used for other elements.

********************
Additional variables
********************

Keep in mind that, in general use case, the "layout" and "template" parameters 
should be enough to get the result you want. The following parameters are 
documented for contributors:

* settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT: allows you to change the implicit
  value of the "layout" parameter. Default value is "default". Notice that you 
  can get exactly the same result by overriding the form_layouts/default/* 
  templates: simply make sure that the templates in your project/application 
  have priority over the ones provided by formrenderingtools.
* settings.FORMRENDERINGTOOLS_DEFAULT_TEMPLATE: allows you to change the 
  implicit value of the "template" parameter. Default value is "default.html". 
  Notice that you can get exactly the same result by overriding the 
  form_layouts/default/{ELEMENT_NAME}/default.html templates: simply make sure 
  that the templates in your project/application have priority over the ones 
  provided by formrenderingtools.
* settings.FORMRENDERINGTOOLS_TEMPLATE_DIR. A prefix for all templates used by
  the django-formrenderingtools application. It is not recommended to change
  it, because you should be able to perform the same thing by using one of the 
  previously described tip.