Forms are validated in Glashammer using WTForms. The forms bundle in Glashammer does not have to be used, it only helps by adding some features that may help you in addition to WTForms.
A form has any number of fields, and each of these fields has any number of validators. Fields are of different types that reflect the different types of data you wish to get from the request.
A form should first be defined as a class with a declarative syntax like so:
from wtforms import Form, TextField, PasswordField
class LoginForm(Form):
"""My login form"""
username = TextField()
password = PasswordField()
This form contains two fields, a username and a password.
The form above is just a definition of the form. To make it useful, the form should instantiated and loaded with form data.
This usually occurs during a request in a view callable, for example:
def do_login(request):
form = LoginForm(request.form)
A form instance can do a number of things. Firstly the form data passed on construction may be validated using the wtforms.Form.validate() method like so:
def do_login(request):
form = LoginForm(request.form)
if form.validate():
# Form is valid
pass
The form instance may also be used to populate a python instance, using the wtforms.Form.auto_populate() method. So using a slightly different example where this might make sense:
def do_comment(request):
form = CommentForm(request.form)
if form.validate():
# Form is valid
comment = Comment()
form.auto_populate(comment)
The usual pattern is to pass the form instance into the template’s context during a glashammer.utils.render_response() call like so:
def do_comment(request):
if request.method == 'GET':
# it's a get, so just show the form
form = CommentForm()
return render_response('add_comment.html', form=form)
And thus the form instance will be available in the template.
From the template, a number of things can be accessed:
A quick rendering of each field can be performed on the form by accessing the field by name, for example:
{{ form.username }}
This is the simple way. In reality it is actually calling the form.username() function. Any html parameter can be passed into this call, for example:
{{ form.password(style="width: 200px;" max_length=15) }}
The label for each field can also be accessed, with:
{{ form.username.label }}
Rendering an html label for use in the form.
Jinja2 allows you to use dict-like attribute markup, so if your field name is a variable, you can access it like:
{{ form[field_name] }}
So, for a complete form, we might have:
<form method="post" action="">
{{ form.username.label }} {{ form.username }}
{{ form.password.label }} {{ form.password }}
<input type="submit" value="Log in" />
</form>
Note
There is nothing to stop you from hand-writing your form markup, and for more complicated forms you certainly will have to. The validation for the form stays the same though, and you have a nice graded path from automatic generation to hand-written.
Form base class. Provides core behaviour like field construction, validation, and data and error proxying.
Populates the attributes of the passed obj with data from the form’s fields.
Note: This is a destructive operation, any attribute with the same name as a field will be overridden. Use with caution.
Validates the form by calling validate on each field, passing any extra Form.validate_<fieldname> validators to the field validator.
Returns True if no errors occur.
A text field which displays and coerces data of the decimal.Decimal type.
Defining the number_format parameter to the constructor allows you to customize how the number is displayed, using standard python string formatting rules.
Encapsulate an ordered list of multiple instances of the same field type, keeping data as a list.
>>> authors = FieldList(TextField('Name', [validators.required()]))
| Parameters: |
|
|---|
Encapsulate a form as a field in another form.
| Parameters: |
|
|---|
Like a SelectField, except displays a list of radio buttons.
Iterating the field will produce subfields (each containing a label as well) in order to allow custom rendering of the individual radio fields.
Validates an email address. Note that this uses a very primitive regular expression and should only be used in instances where you later verify by other means, such as email activation or lookups.
| Parameters: |
|
|---|
Compares the values of two fields.
| Parameters: |
|
|---|
Validates an IP(v4) address.
| Parameters: |
|
|---|
Validates the length of a string.
| Parameters: |
|
|---|
Validates that the field contains data. This validator will stop the validation chain on error.
| Parameters: |
|
|---|
Validates the field against a user provided regexp.
| Parameters: |
|
|---|
Simple regexp based url validation. Much like the email validator, you probably want to validate the url later by other means if the url must resolve.
| Parameters: |
|
|---|