Forms

Foundation’s form component is complex and provides many options. The foundation_form template tag enables you to render your Form objects with complete control over their layout.

Basic Usage

To use the template tag at it’s most basic, don’t provide any options between the open and closing tags, and pass your Form object:

<form>
{% foundation_form my_form_object %}
{% end_foundation_form %}
</form>

This will render all your specified form fields at full width. (In Foundation’s grid terms, this means they are defined as small-12, medium-12 and large-12.)

Note

Just like Django’s own form rendering, the template tag will not render the opening and closing <form> elements, or the submit button. That’s up to you.

CSRF

By default, the foundation_form template tag will insert the csrf_token required by django.middleware.csrf.CsrfViewMiddleware. If you’re not using this middleware, or don’t want the token itself, you can set csrf_enabled to False in the tag:

{% foundation_form my_form_object csrf_enabled=False %}
{% end_foundation_form %}

Collapsing the containing row

If you wish to use the form in the Right Menu, or somewhere else where you do not wish the extra side padding for the form elements, set collapse_container to True:

{% foundation_form my_form_object collapse_container=True %}
{% end_foundation_form %}

Layout Customisation

To customise which fields appear next to each other in the form, specify each row as a semi-colon-separated list between the form tags. For example, for a imaginary ‘Customer’ form:

{% foundation_form customer_form %}
    title; first_name; last_name
    email_address;
    password; confirm_password;
{% end_foundation_form %}

This will render the title, first_name and last_name fields at equal widths on one row, the email_address field on it’s own row, and then the two password fields equal width on the final row. Again, in Foundation’s grid terms, this means that the three first-row fields will have small-12, medium-4 and large-4, the email_address is small-12 etc., and the password fields are small-12, medium-6 and large-6 etc.

Any fields you do not specify will be appended to the end of the form at full width.

Note

No matter which fields you specify on each line, Nuit will default all fields to their own line for small screens (small-12). This can be overriden - see the Custom Widths section.

Custom Widths

If you don’t want to rely on Nuit’s automatic spacing of fields (for example, you know that the title field really out to be smaller than the field_name and last_name fields), you can provide a dict of options after each field containing values for either small, medium or large depending on what you want to override. For example, to make the title field take up 2 columns at medium-up, use the following markup:

{% foundation_form customer_form %}
    title {'medium': 2}; first_name; last_name
    email_address;
    password; confirm_password;
{% end_foundation_form %}

Nuit will automatically space out unspecified width fields as best it can to fill the remaining space.

Note

Just like Foundation, widths defined for smaller sizes will be inherited by larger sizes. In the example above, even though we only specify the medium value, the title field also take a width of 2 at large sizes. If you don’t want this behaviour, then either set the larger sizes manually, or set the next size up to 0 to let Nuit calculate the spacings.

Pre- and Post-fix Labels

Foundation allows you to define pre- and post-fix labels that attach to form inputs. One example of such usage is prepending a http:// before an input asking for a URL (note that this data is not included in the submitted data). Nuit lets you define this in the field’s data dict:

{% foundation_form customer_form %}
    title; first_name; last_name
    email_address {'postfix': '@gmail.com'};
    password {'prefix': '6 chars or less'}; confirm_password;
{% end_foundation_form %}

Custom Widths

By default, each pre- or post-fix label will take up 3 of the 12 available grid widths at all sizes, and the field will take up 9. This can be customised in exactly the same way as for fields, detailed above in Custom Widths. Add options to the dict of prefix_small, prefix_medium, prefix_large, postfix_small, postfix_medium and postfix_large:

{% foundation_form customer_form %}
    title; first_name; last_name
    email_address {'postfix': '@gmail.com', 'postfix_medium': 4};
    password {'prefix': '6 chars or less'}; confirm_password;
{% end_foundation_form %}

The same rules for inheritance apply as in the note above.

Additional Field Options

The following options are also available in the field option dict:

show_label
Default:True

Whether to display the field’s label or not.