wtforms / docs / forms.rst

Full commit


Forms provide the highest level API in WTForms. They contain your field definitions, delegate validation, take input, aggregate errors, and in general function as the glue holding everything together.

Defining forms

To define a form, one makes a subclass of :class:`Form` and defines the fields declaratively as class attributes:

class MyForm(Form):
    first_name = TextField(u'First Name', validators=[validators.required()])
    last_name  = TextField(u'Last Name', validators=[validators.optional()])

Field names can be any valid python identifier, with the following restrictions:

  • Field names are case-sensitive.
  • Field names may not begin with "_" (underscore)
  • Field names may not begin with "validate"

Form Inheritance

Forms may subclass other forms as needed. The new form will contain all fields of the parent form, as well as any new fields defined on the subclass. A field name re-used on a subclass causes the new definition to obscure the original.

class PastebinEdit(Form):
    language = SelectField(u'Programming Language', choices=PASTEBIN_LANGUAGES)
    code     = TextAreaField()

class PastebinEntry(PastebinEdit):
    name = TextField(u'User Name')

In-line validators

In order to provide custom validation for a single field without needing to write a one-time-use validator, validation can be defined inline by defining a method with the convention validate_fieldname:

class SignupForm(Form):
    age = IntegerField(u'Age')

    def validate_age(form, field):
        if < 13:
            raise ValidationError("We're sorry, you must be 13 or older to register")

Using forms

A form is most often constructed in the controller code for handling an action, with the form data wrapper from the framework passed to its constructor, and optionally an ORM object. The constructed form can then validate any input data and generate errors if invalid. The form object can then be passed along to template code to render the form fields along with any errors which occurred.