A designer-focused forms control library which works as a layer over the standard Django forms API.

Render one or more forms. A basic example of rendering a standard form using HTML paragraphs for rows would be {% form some_form using "forms/p.html" %}.

Usage:

{% form some_form [form2 form3 ...] %}

Any of the standard tag arguments can be used.

Context:

forms

List of forms to render.

errors

Set to True if any of the forms contain errors.

non_field_errors

List of non-field errors.

Used to render a row template with one or more fields with the currently defined template.

Usage is either:

* ``{% row field_list %}``
* ``{% row some_form.field [some_form.field ...] %}``

Any of the standard tag arguments can be used.

Context:

fields

List of fields to render.

errors

List of errors relating to any of the fields in this row.

required

The number of fields that are required.

Used to render a specific field with the currently defined field template.

Usage:

{% field some_field %}

Requires a context variable named form to exist (and be a django.forms.forms.BaseForm` instance).

Any of the standard tag arguments can be used.

Context:

value

The value of this field.

errors

A list of errors relating to this field.

label

The label text for this field.

help_text

The help text for this field.

form

The form this field belongs to.

field

The underlying form field being rendered.

id

The id for this field (or an empty string).

id_for_label

The id which should be assigned to the field's label

name

The name of this field.

html_name

The prefixed name of this field

Used to configure rows and fields, as specified by the first tag argument. Reuse of this tag overrides previously defined matching configurations.

Usage, either:

* ``{% formconfig row ... %}``, or
* ``{% formconfig field ... %}``

Any of the standard `tag arguments`_ can be used.

To limit the configuration of rows for one or more specific fields, use the for argument. For example:

{% formconfig row for form.first_name form.last_name using "forms/rows/pretty.html" %}

The for argument also accepts strings:

{% formconfig field for "email" with help_text="Your email address" %}

Use the priority argument to change the default order of form fields. This can only be used if the configuration is limited to specific fields. For example:

{% formconfig field for form.first_name priority 1 %}
{% formconfig field for form.last_name priority 2 %}

These arguments can be used on any form-related tag.

with key=value [key=value key=value ...]

Adds to the context of the template which will be rendered.

If this argument is part of the tag, the current context will not be available to the template that will be rendered.

There are two arguments that allow configuration of which template should be used to render the template:

using some_template or using (as the final tag argument)

Specify the template to use.

extends some_template or extends (as the final tag argument)

Extends an existing template (via the use of {% block %} tags). See the Extend form-related templates inline section.

The using argument without a template or either form of the extends argument means that the template is being defined inline until a closing {% end- tag is reached (matching the opening tag, for example, {% form extends "forms/custom.html" %}...{% endform %}).

{% get_ordered_fields %} --------------------------

Used by form templates to retrieve an ordered list of form fields.

Usage:

{% get_ordered_fields forms_list as var_name %}

Adds a context variable containing a list of fields.

Not specific to forms, a useful tag which allows wrapping text if the content contains non-whitespace. For example, conditionally showing the help text div inside of the field template:

{% ifcontent %}
    <div class="helptext">
        {% content %}
            {% block help %}{{ help_text }}{% endblock %}
        {% endcontent %}
    </div>
{% endifcontent %}

Here are some basic examples:

{% form form1 form2 extends "forms/p.html" %}

    {% block config %}
        {% formconfig field using "forms/fields/booleanselect.html" for form1.accept_tos %}
    {% endblock %}

{% endform %}


{% form form1 extends "forms/p.html" %}

    {% block config %}
        {### Set all rows to use a special "p", except for the TOS #}
        {% formconfig row using "forms/rows/special-p.html" %}
        {% formconfig row using "forms/rows/p.html" for form1.accept_tos %}
    {% endblock %}

{% endform %}

And here's one more slightly more complex example that extends both the form and a field's template:

{% form extends "forms/p.html" %}

    {% block config %}
        {% formconfig field for form.is_manager extends %}
            {% block help %}{% blocktrans with site=site.name %}Can this person manage {{ site }}?{% endblocktrans %}{% endblock %}
        {% endformconfig %}
    {% endblock %}

    {% block fields %}
        {% row form.first_name form.last_name %}
        {% row form.email with class="email" %}
        {% row form.is_manager %}
    {% endblock fields %}

{% endform %}

Use the priority argument of formconfig-tag to order fields without the need to manually redefine all fields in the form. To give fields a priority to the top of the form, use positive integers (the lower the number, the higher priority).

Use negative integers to give fields a low priority (i.e. occuring after both those with a positive priority and those without a priority set at all).

If multiple fields are given the same priority, the fields configured first will have the highest priority:

{% form form1 form2 extends "forms/p.html" %}

    {% block config %}
        {### Put these three fields to the top, in this order #}
        {% formconfig field for "first_name" priority 1 %}
        {% formconfig field for "last_name" priority 1 %}
        {% formconfig field for "email" priority 1 %}
        {### And put this one to the bottom #}
        {% formconfig field for "accept_tos" priority -1 %}
    {% endblock %}

{% endform %}

If you are creating an entire form template, use this tag to initiate the reordering of a form's fields:

{% formreorder form %}

This is done in all the built-in form templates.

forms/p.html:

{% block allconfig %}
    {% formconfig row using "forms/rows/p.html" %}
    {% block config %}{% endblock %}
{% endblock %}

{% if non_field_errors %}
<ul class="errors">
    {% for errors in form.non_field_errors %}
    <li>{{ errors }}</li>
    {% endfor %}
</ul>
{% endif %}

{% get_rows_ordered forms as rows %}
{% block rows %}
{% for fields in rows %}
    {% row fields %}
{% endfor %}
{% endblock %}

forms/rows/base.html:

{% block row_start %}{% endblock %}
{% for form, field in fields %}
    {% block start %}{% endblock %}
    {% field field %}
    {% block end %}{% endblock %}
{% endfor %}
{% block row_end %}{% endblock %}

forms/rows/p.html:

{% extends "forms/rows/base.html" %}
{% block start %}<p{% if errors or required %} class="{% if errors %}errors{% if required %} {% endif %}{% endif %}{% if required %}required{% endif %}"{% endif %}>{% endblock %}
{% block end %}</p>{% endblock %}

form/fields/base.html:

{% if label %}
    <label{% if id_for_label %} for="{{ id_for_label }}">{% block label %}{{ label }}{% endblock %}</label>
{% endif %}
<input type="text" value="{{ value }}" id="{{ id }}" />
{% if errors %}
<ul class="errors">
{% for error in errors %}
    <li>{{ error }}</li>
{% endfor %}
</ul>
{% endif %}
{% ifcontent %}
    <span class="helptext">
        {% content %}
            {% block help %}{{ help_text }}{% endblock %}
        {% endcontent %}
    </span>
{% endifcontent %}