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:

    {% 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:

    {% 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.

Table Of Contents

Previous topic

Settings

Next topic

Cascading style sheets

This Page