WTForms-Dynamic-Fields 0.1a3

Installation

Simply use pip to install:

pip install wtforms-dynamic-fields --pre

The ‘–pre’ flag is necessary until this module has an official release.

Then include it in your project:

A few notes before using this module

If you simply want to add one field to an already existing form, it may be less overhead to simply use setattr:

setattr(Form, field_name, TextField(field_label, validators=[InputRequired()]))

Doing so will attach a text field, with one validator to the “Form” object. This module is intended for slightly more complex scenarios and to offer an easier way of configuration.

Also, this module, in its current state, is developed to scratch a personal itch - simple server side validation of dynamic fields (through WTForms itself). It is most likely missing some needed flexibility and/or features, so do not hesitate to pinch in or drop me a line!

Quick overview

Basic usage

The idea behind this module is that you can add “dynamic” fields to a form that has already been created. “Dynamic” here means fields that are not rendered (nor present in the original form object) initially, but get injected into the DOM afterwards.

The module uses the POST variables together with a user defined configuration to determine which fields are new and are allowed to be processed.

The first thing you need, obviously, is a valid WTForms instance to put the new fields on. Say, for example, we have a form that contains a first name and a last name field, this would be declared as follows:

from wtforms import Form, TextField
from wtforms.validators import InputRequired

class PersonalFile(Form):
    """ A personal file form. """
    first_name = TextField('First name, validators=[InputRequired()])
    last_name = TextField('Last name, validators=[InputRequired()])

When we present this form to our user, we wish to have the ability to optionally add an email address and make it required once added.

In most cases, to make for a nice user experience, we go ahead an create a button that has some JavaScript bound to it which will inject the new email input field. Also, because we all like instant feedback glory, we could add some client side validation in our JavaScript to catch mistakes early and prevent a round trip to the server.

However, we also want this new email address field to be correctly validated on the server and, in case when validation fails, be rendered back to the user for inspection. We do not want to write our own validation code for this field, but leverage the power of the already present, full-blown WTForms form library to do the heavy lifting.

This is where this module steps in.

First you will need an instance of the module:

dynamic = WTFormsDynamicFields()

Next you will need to build the configuration which will hold the allowed, dynamic fields (and their validators). To do this, you use the “add_field” method: define the fields machine name, the label and finally a WTForms field type:

dynamic.add_field('email', 'Email address', TextField)

Optionally, you can pass *args and **kwargs to the field as well.

Of course, the machine name of the field needs to correspond with the input’s “name” attribute as injected by JavaScript. Also notice we do not add any parenthesis after the WTForms field type (TextField).

If needed, you can also apply optional validators by using the “add_validator” method. You define on which field you wish to apply the validator and you pass in a WTForms validator:

dynamic.add_validator('email', InputRequired, message='This field is required')

Here too you have the ability to pass in optional *args and **kwargs to the validator. Again, no parenthesis after InputRequired, its arguments will be bound by the module later on.

Now that you have added this email field and pushed a validator on it, you are ready to process your form. For the form to be processed, you will need your original form (PersonalFile in our case) and the POST that comes back from the server.

Normally, you would bind your form variable directly to the WTForm instance:

form = PersonalFile()

To enable this module to process you form, however, you simply need to wrap its “process” method around it and add the incoming POST:

form = dynamic.process(PersonalFile, request.post)

Now the form will pick up the optional email field when injected and make the validation fail server side if the field is left empty. Removing the field from the DOM will make your form pass validation again (given that you filled in the first_name and last_name fields, that is).