WTForms-Components¶
WTForms-Components provides various additional fields, validators and widgets for WTForms.
Fields¶
WTForms derived HTML5 Fields¶
WTForms-Components provides enhanced versions of WTForms HTML5 fields. These fields support HTML5 compatible min and max validators. WTForms-Components is smart enough to automatically attach HTML5 min and max validators based on field’s NumberRange and DateRange validators.
Example:
from wtforms import Form
from wtforms_components import DateTimeField
from werkzeug.datastructures import MultiDict
class TestForm(Form):
test_field = DateTimeField(
'Date',
validators=[DateRange(
min=datetime(2000, 1, 1),
max=datetime(2000, 10, 10)
)]
)
form = TestForm(MultiDict(test_field='2000-2-2'))
form.test_field
# <input id="test_field" max="2000-10-10 00:00:00" min="2000-01-01 00:00:00" name="test_field" type="datetime" value="2000-2-2">'
Same applies to IntegerField:
from wtforms import Form
from wtforms_components import IntegerField
from werkzeug.datastructures import MultiDict
class TestForm(Form):
test_field = IntegerField(
'Date',
validators=[NumberRange(
min=1,
max=4
)]
)
form = TestForm(MultiDict(test_field='3'))
form.test_field
# <input id="test_field" max="4" min="1" name="test_field" type="number" value="3">'
SelectField & SelectMultipleField¶
WTForms-Components provides enhanced versions of WTForms SelectFields. Both WTForms-Components SelectField and SelectMultipleField support the following enhancements:
- Ability to generate optgroup elements.
choices
can be a callable, which allows for dynamic choices. With the plain version of WTForms this has to be added manually, after instantiation of the form.
PhoneNumberField¶
Older versions of WTForms-Components had a PhoneNumberField. As of version 0.10.0 this field has now been moved to WTForms-Alchemy.
ColorField¶
ColorField is a string field representing a Color object from colour package.
Example:
from wtforms import Form
from wtforms_components import ColorField
class DocumentForm(Form):
background_color = ColorField()
NumberRangeField¶
NumberRangeField is a string field representing a NumberRange object from SQLAlchemy-Utils.
Example:
from wtforms import Form
from wtforms_components import NumberRangeField
class EventForm(Form):
estimated_participants = NumberRangeField('Estimated participants')
TimeField¶
TimeField is a string field which stores a datetime.time matching a format.
from wtforms import Form, DateField
from wtforms_components import TimeField
class EventForm(Form):
start_date = DateField('Start date')
start_time = TimeField('Start time')
Read-only fields¶
WTForms-Components provides a convenient function for making fields read-only.
In the following example we define a form where name field is defined as read-only.
from wtforms import Form, DateField, TextField
from wtforms_components import TimeField, read_only
class EventForm(Form):
name = TextField('Name')
start_date = DateField('Start date')
start_time = TimeField('Start time')
def __init__(self, *args, **kwargs):
super(EventForm, self).__init__(*args, **kwargs)
read_only(self.name)
Validators¶
DateRange validator¶
The DateRange validator is essentially the same as wtforms.validators.NumberRange validator but validates dates.
In the following example we define a start_time and a start_date field, which do not accept dates in the past.
from datetime import datetime, date
from wtforms import Form
from wtforms.fields import DateField
from wtforms_components import DateRange
class EventForm(Form):
start_time = DateField(
validators=[DateRange(min=datetime.now())]
)
start_date = DateField(
validators=[DateRange(min=date.today())]
)
Email validator¶
Validates an email address. This validator is based on `Django's email validator`_ and is stricter than the standard email validator included in WTForms.
Example:
from wtforms import Form
from wtforms.fields import TextField
from wtforms_components import Email
class UserForm(Form):
email = TextField(
validators=[Email()]
)
If validator¶
The If validator provides means for having conditional validations. In the following example we only validate field email if field user_id is provided.
from wtforms import Form
from wtforms.fields import IntegerField, TextField
from wtforms_components import If
class SomeForm(Form):
user_id = IntegerField()
email = TextField(validators=[
If(lambda form, field: form.user_id.data, Email())
])
Chain validator¶
Chain validator chains validators together. Chain validator can be combined with If validator to provide nested conditional validations.
from wtforms import Form
from wtforms.fields import IntegerField, TextField
from wtforms_components import If
class SomeForm(Form):
user_id = IntegerField()
email = TextField(validators=[
If(
lambda form, field: form.user_id.data,
Chain(DataRequired(), Email())
)
])
Unique Validator¶
Unique validator provides convenient way for checking the unicity of given field in database.
As of WTForms-Components version 0.10.0 the Unique validator has been moved to WTForms-Alchemy due to its SQLAlchemy dependency.