What is a FormHelper and how to use it, is throughly explained in a previous section {% crispy %} tag with forms.
Since version 1.2.0 FormHelper optionally can be passed an instance of a form. You would do it this way:
class ExampleForm(forms.Form):
def __init__(self, *args, **kwargs):
super(ExampleForm, self).__init__(*args, **kwargs)
self.helper = FormHelper(self)
When you do this crispy-forms builds a default layout using form.fields for you, so you don’t have to manually list them all if your form is huge. If you later need to manipulate some bits of a big layout, using dynamic layouts is highly recommended, check Updating layouts on the go.
Also, now the helper is able to cross match the layout with the form instance, being able to search by widget type if you are using dynamic API.
Applied to the form action attribute. Can be a named url in your URLconf that can be executed via the {% url %} template tag. Example: ‘show_my_profile’. In your URLconf you could have something like:
url(r'^show/profile/$', 'show_my_profile_view', name='show_my_profile')
You can also point it to a URL ‘/whatever/blabla/’.
Sometimes you may want to add arguments to the URL, for that you will have to do in your view:
from django.core.urlresolvers import reverse
form.helper.form_action = reverse('url_name', args=[event.id])
form.helper.form_action = reverse('url_name', kwargs={'book_id': book.id})
Added in 1.2.0, a dictionary to set any kind of form attributes. Underscores in keys are translated into hyphens. The recommended way when you need to set several form attributes in order to keep your helper tidy:
``{'id': 'form-id', 'data_id': '/whatever'}``
<form id="form-id" data-id="/whatever" ...>
There are currently some helper attributes that only have functionality for a specific template pack. This doesn’t necessarily mean that they won’t be supported for other template packs in the future.
All previous, bootstrap (version 2) attributes are also settable in bootstrap 3 template pack FormHelpers. Here are listed the ones, that are only available in bootstrap3 template pack:
Maybe you would like that FormHelper did some extra thing that is not currently supported or maybe you have a very specific use case. The good part is that you can add extra attributes and crispy-forms will automagically inject them within template context. Let’s see an example, to make things clear.
We want some forms to have labels uppercase, for that we would like to set a helper attribute name labels_uppercase to True or False. So we go and set in our helper:
helper.labels_uppercase = True
What will happen is that crispy-forms will inject a Django template variable named {{ labels_uppercase }} with its corresponding value within its templates, including field.html, which is the template in charge of rendering a field when using crispy-forms. So we can go into that template and customize it. We will need to get familiar with it, but it’s quite easy to follow, in the end it’s only a Django template.
When we find where labels get rendered, this chunk of code to be more precise:
{% if field.label and not field|is_checkbox and form_show_labels %}
<label for="{{ field.id_for_label }}" class="control-label {% if field.field.required %}requiredField{% endif %}">
{{ field.label|safe }}{% if field.field.required %}<span class="asteriskField">*</span>{% endif %}
</label>
{% endif %}
The line that we would change wold end up like this:
{% if not labels_uppercase %}{{ field.label|safe }}{% else %}{{ field.label|safe|upper }}{% endif %}{% if field.field.required %}
Now we only need to override field template, for that you may want to check section Overriding layout objects templates.
Warning
Be careful, depending on what you aim to do, sometimes using dynamic layouts is a better option, check section Updating layouts on the go.