Combining multiple forms in Flask-WTForms but validating independently
Tags: flask, wtforms, python
Published: 2019-01-17 12:07:04

---
title: Combining multiple forms in Flask-WTForms but validating independently
published: true
description: How to create a Flask form made up of subforms and then to validate and save just those subforms.
tags: flask, wtforms, python
canonical_url: https://blog.whiteoctober.co.uk/2019/01/17/combining-multiple-forms-in-flask-wtforms-but-validating-independently/
---

# Introduction

We have a Flask project coming up at [White October](https://www.whiteoctober.co.uk/) 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](http://wtforms.simplecodes.com/docs/1.0.1/fields.html#field-enclosures) 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](https://stackoverflow.com/a/35776874/328817) 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](http://flask.pocoo.org/docs/1.0/patterns/wtforms/#forms-in-templates) 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 <code>[items](https://docs.python.org/3/tutorial/datastructures.html#looping-techniques)</code> 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](https://medium.com/@doobeh/posting-a-wtform-via-ajax-with-flask-b977782edeee)", 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](https://api.jquery.com/serialize/).  However, the data produced by this method doesn't include details of the button clicked to submit the form.

There are [various ways](https://stackoverflow.com/questions/4007942/jquery-serializearray-doesnt-include-the-submit-button-that-was-clicked) 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](https://stackoverflow.com/a/11271850/328817)).  That way, Python code like `if "submit-about-you" in request.form` (see above) can remain unchanged whether you're using AJAX or postbacks.