Introduction

We have a Flask project coming up at White October which will include a user profile form. This form can be considered as one big form or as multiple smaller forms and can also be submitted as a whole or section-by-section.

As part of planning for this work, we did a proof-of-concept around combining multiple subforms together in Flask-WTForms and validating them.

Note that this is a slightly different pattern to "nested forms". Nested forms are often used for dynamic repeated elements - like adding multiple addresses to a profile using a single nested address form repeatedly. But our use case was several forms combined together in a non-dynamic way and potentially processed independently. This article also doesn't consider the situation of having multiple separate HTML forms on one page.

This document explains the key things you need to know to combine forms together in Flask-WTF, whether you're using AJAX or plain postback.

Subforms

The first thing to know is how to combine multiple WTForms forms into one. For that, use the FormField field type (aka "field enclosure"). Here's an example:

from flask_wtf import FlaskForm
import wtforms

class AboutYouForm(FlaskForm):
    first_name = wtforms.StringField(
        label="First name", validators=[wtforms.validators.DataRequired()]
    )
    last_name = wtforms.StringField(label="Last name")

class ContactDetailsForm(FlaskForm):
    address_1 = wtforms.StringField(
        label="Address 1", validators=[wtforms.validators.DataRequired()]
    )
    address_2 = wtforms.StringField(label="Address 2")

class GiantForm(FlaskForm):
    about_you = wtforms.FormField(AboutYouForm)
    contact_details = wtforms.FormField(ContactDetailsForm)

As you can see, the third form here is made by combining the first two.

You can render these subforms just like any other form field:

{{ form.about_you }}

(Form rendering is discussed in more detail below.)

Validating a subform

Once we'd combined our forms, the second thing we wanted to prove was that they could be validated independently.

Normally, you'd validate a (whole) form like this:

if form.validate_on_submit()
    # do something

(validate_on_submit returns true if the form has been submitted and is valid.)

It turns out that you can validate an individual form field quite easily. For our about_you field (which is a subform), it just looks like this:

form.about_you.validate(form)

Determining what to validate

We added multiple submit buttons to the form so that either individual subforms or the whole thing could be processed. If you give the submit buttons different names, you can easily check which one was pressed and validate and save appropriately (make sure you only save the data you've validated):

<input type="submit" name="submit-about-you" value="Just submit About You subform">
<input type="submit" name="submit-whole-form" value="Submit whole form">

And then:

if "submit-about-you" in request.form and form.about_you.validate(form):
    # save About You data here
elif "submit-whole-form" in request.form and form.validate():
    # save all data here

If you have one route method handling both HTTP GET and POST methods, there's no need to explicitly check whether this is a postback before running the above checks - neither button will be in request.form if it's not a POST.

Alternative approaches

You could alternatively give both submit buttons the same name and differentiate on value. However, this means that changes to the user-facing wording on your buttons (as this is their value property) may break the if-statements in your code, which isn't ideal, hence why different names is our recommended approach.

If you want to include your submit buttons in your WTForms form classes themselves rather than hard-coding the HTML, you can check which one was submitted by checking the relevant field's data property - see here for a small worked example of that.

Gotcha: Browser-based validation and multiple submit buttons

There's one snag you'll hit if you're using multiple submit buttons to validate/save data from just one subform of a larger form.

If your form fields have the required property set (which WTForms will do if you use the DataRequired validator, for example), then the browser will stop you submitting the form until all required fields are filled in - it doesn't know that you're only concerned with part of the form (since this partial-submission is implemented server-side).

Therefore, assuming that you want to keep using the required property (which you should), you'll need to add some Javascript to dynamically alter the form field properties on submission.

This is not a problem if you're using AJAX rather than postbacks for your form submissions; see below how to do that.

Rendering subforms in a template

The examples in this section use explicit field names. In practice, you'll want to create a field-rendering macro to which you can pass each form field rather than repeating this code for every form field you have. That link also shows how to render a field's label and widget separately, which gives you more control over your markup.

As mentioned above, the subforms can be rendered with a single line, just like any other field:

{{ form.about_you }}

If you want to render fields from your subforms individually, it'll look something like this:

<label for="{{ form.about_you.first_name.id }}">{{ form.about_you.first_name.label }}</label>
{{ form.about_you.first_name }}

As you see, you can't do single-line rendering of form fields and their labels for individual fields within subforms - you have to explicitly render the label.

Displaying subform errors

For a normal form field, you can display associated errors by iterating over the errors property like this:

{% if form.your_field_name.errors %}
    <ul class=errors>
        {% for error in field.errors %}
            <li>{{ error }}</li>
        {% endfor %}
    </ul>
{% endif %}

In this case, errors is just a list of error strings for the field.

For a subform where you're using the FormField field type, however, errors is a dictionary mapping field names to lists of errors. For example:

{
    'first_name': ['This field is required.'],
    'last_name': ['This field is required.'],
}

Therefore, iterating over it in your template is more complicated. Here's an example which displays errors for all fields in a subform (notice the use of the items method):

{% if form.about_you.errors %}
    <ul class="errors">
        {% for error_field, errors in form.about_you.errors.items() %}
            <li>{{ error_field }}: {{ errors|join(', ') }}</li>
        {% endfor %}
    </ul>
{% endif %}

Doing it with AJAX

So far, we've considered the case of validating subforms when data is submitted via a full-page postback. However, you're likely to want to do subform validation using AJAX, asynchronously posting form data back to the Flask application using JavaScript.

There's already an excellent article by Anthony Plunkett entitled "Posting a WTForm via AJAX with Flask", which contains almost everything you need to know in order to do this.

In this article, therefore, I'll just finish by elaborating on the one problem you'll have if doing this with multiple submit buttons - determining the submit button pressed

Determining the submit button pressed

When posting data back to the server with JavaScript, you're likely to use a method like jQuery's serialize. However, the data produced by this method doesn't include details of the button clicked to submit the form.

There are various ways you can work around this limitation. The approach I found most helpful was to dynamically add a hidden field to the form with the same name and value as the submit button (see here). That way, Python code like if "submit-about-you" in request.form (see above) can remain unchanged whether you're using AJAX or postbacks.