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.