WTForms integration

Important Documentation below is related to project version 2.0.0 or higher. Old versions have completely different behaviour. And despite the fact that the old code is included in version 2.0.0 to keep correct deprecation workflow (where possible), it is not documented and not maintained. If you faced any forms problems, consider migration to new methods and approach.

Requirements

Flask-Mongoengine and Flask-WTF/WTForms are heavily integrated, to reduce the amount of boilerplate code required to make a database model and online form. At the same time a lot of options were created to keep extreme flexibility. After database model definition, users do not require to repeat same code in form definition — instead it is possible to use the integrated converter that will do most of the work.

Flask-Mongoengine will transform some model's properties to Flask-WTF/WTForms validators, so users do not need to care about standards. For full list of transformations, please review global transforms and specific field documentation below.

For correct integration behavior, several requirements should be met:

Document classes should be used from Flask-Mongoengine flask_mongoengine.MongoEngine class, or from flask_mongoengine.documents module.
Document classes should be used from Flask-Mongoengine flask_mongoengine.MongoEngine class, or from flask_mongoengine.db_fields module.
For all fields processed by Flask-Mongoengine integration: if model field definition has wtf_validators defined, they will be forwarded to WTForm as validators. This is not protection from validators extension by Flask-Mongoengine.
Field's default used as form default — that's why special WTForms fields implementations were created. Details can be found in flask_mongoengine.wtf.fields module. In the new form generator only 'Mongo' prefixed classes are used for fields; other classes are deprecated and will be removed in version 3.0.0.
Field's choices, if they exist, are used as form choices.

Global transforms

Flask-Mongoengine will transform some model's properties to Flask-WTF/WTForms validators automatically. Some additional transformations are made by specific fields — check the exact field documentation below for more info.

Note As of version 2.0.0 there is no wtf_validators duplicates/conflicts check. Users should be careful with manual wtf_validators setup. And in case of form problems this is the first place to look. wtf_validators and wtf_filters duplication check is expected in future versions; PRs are welcome.

BinaryField

Not yet documented. Please help us with a new pull request.

BooleanField

Not yet documented. Please help us with a new pull request.

ComplexDateTimeField

During WTForm generation this field uses wtforms.fields.DateTimeLocalField with milliseconds accuracy. Direct microseconds are not supported by browsers for this type of field. If exact microseconds support is required, please use wtforms.fields.DateTimeField with extended text format set. Examples available in example app. This does not affect in-database accuracy.

"""dates_demo.py"""
from wtforms.fields import DateTimeField
from example_app.models import db

class DateTimeModel(db.Document):
    """Documentation example model."""
    complex_datetime_microseconds = db.ComplexDateTimeField(
        wtf_field_class=DateTimeField,
        wtf_options={"format": "%Y-%m-%d %H:%M:%S.%f"}
    )

DateField

DateField is one of the simplest fields in the forms generation process. By default, the field uses wtforms.fields.DateField WTForms class, representing a form input with standard HTML5 <input type="date">. No custom additional transformation is done during field generation. Field is fully controllable by global transforms.

"""dates_demo.py"""
from example_app.models import db

class DateTimeModel(db.Document):
    """Documentation example model."""
    date = db.DateField()

DateTimeField

Not yet documented. Please help us with a new pull request.

DecimalField

If database field definition has any of min_value or max_value, then NumberRange validator will be added to the form.

Changed in version 2.0.0: Default form field class changed from wtforms.fields.DecimalField to MongoDecimalField.

DictField

Not yet documented. Please help us with a new pull request.

EmailField

Field respects user's adjustments in wtf_field_class option of db_fields.EmailField. This will change form field display, but will not change inserted validators.

"""strings_demo.py"""
from example_app.models import db

class StringsDemoModel(db.Document):
    """Documentation example model."""
    url_field = db.EmailField()

EmbeddedDocumentField

Not yet documented. Please help us with a new pull request.

FileField

Not yet documented. Please help us with a new pull request.

FloatField

If database field definition has any of min_value or max_value, then NumberRange validator will be added to the form.

Changed in version 2.0.0: Default form field class changed from wtforms.fields.FloatField to MongoFloatField with 'numbers' input type.

IntField

If database field definition has any of min_value or max_value, then NumberRange validator will be added to the form.

ListField

Not yet documented. Please help us with a new pull request.

ReferenceField

Not yet documented. Please help us with a new pull request.

SortedListField (partly?)

Not yet documented. Please help us with a new pull request.

StringField

By default, during WTForm generation for fields without specified size (min_length or max_length), class MongoTextAreaField is used. In case when min_length or max_length is set, then MongoStringField is used and Length will be added to form field validators. This allows to keep documents of any size in MongoDB.

In some cases class MongoStringField is not the best choice for a field, even with limited size. In this case users can easily overwrite the generated field class by providing wtf_field_class on db_fields.StringField field declaration, either on the document or on form generation steps.

If database field definition has a regex parameter set, then a Regexp validator will be added to the form field.

Note Field declaration step keyword arguments password and textarea are deprecated in Flask-Mongoengine version 2.0.0 and exist only to make migration steps easy. To implement the same behaviour, use wtf_field_class setting on db_fields.StringField init.

"""strings_demo.py"""
from example_app.models import db
from flask_mongoengine.wtf import fields as mongo_fields

class StringsDemoModel(db.Document):
    """Documentation example model."""
    tel_field = db.StringField(wtf_field_class=mongo_fields.MongoTelField)

URLField

Field respects user's adjustments in wtf_field_class option of db_fields.URLField.

Unsupported fields

Not yet documented. Please help us with a new pull request.

Unsure

Not yet documented. Please help us with a new pull request.

← Previous Next →