`_.
For each form you create you also create a validation schema. In our case this is fairly easy:
.. code-block:: python
import formencode
class EmailForm(formencode.Schema):
allow_extra_fields = True
filter_extra_fields = True
email = formencode.validators.Email(not_empty=True)
.. note::
We usually recommend keeping form schemas together so that you have a single
place you can go to update them. It's also convenient for inheritance since
you can make new form schemas that build on existing ones. If you put your
forms in a `models/form.py` file, you can easily use them throughout your
controllers as `model.form.EmailForm` in the case shown.
Our form actually has two fields, an email text field and a submit button. If extra fields are submitted FormEncode's default behavior is to consider the form invalid so we specify `allow_extra_fields = True`. Since we don't want to use the values of the extra fields we also specify `filter_extra_fields = True`. The final line specifies that the email field should be validated with an `Email()` validator. In creating the validator we also specify `not_empty=True` so that the email field will require input.
Pylons comes with an easy to use `validate` decorator, if you wish to use it import it in your `lib/base.py` like this:
.. code-block:: python
# other imports
from pylons.decorators import validate
Using it in your controller is pretty straight-forward:
.. code-block:: python
# in the controller
def form(self):
return render('/form.mako')
@validate(schema=EmailForm(), form='form')
def email(self):
return 'Your email is: %s' % self.form_result.get('email')
Validation only occurs on POST requests so we need to alter our form definition so that the method is a POST:
.. code-block:: mako
${h.form(h.url(action='email'), method='post')}
If validation is successful, the valid result dict will be saved as
`self.form_result` so it can be used in the action. Otherwise, the action will
be re-run as if it was a GET request to the controller action specified in
`form`, and the output will be filled by FormEncode's htmlfill to fill in the
form field errors. For simple cases this is really handy because it also avoids
having to write code in your templates to display error messages if they are
present.
This does exactly the same thing as the example above but works with the
original form definition and in fact will work with any HTML form regardless of
how it is generated because the validate decorator uses `formencode.htmlfill`
to find HTML fields and replace them with the values were originally submitted.
.. note::
Python 2.3 doesn't support decorators so rather than using the
`@validate()` syntax you need to put `email =
validate(schema=EmailForm(), form='form')(email)` after the email
function's declaration.
Validation the Long Way
-----------------------
The `validate` decorator covers up a bit of work, and depending on your needs it's possible you could need direct access to FormEncode abilities it smoothes over.
Here's the longer way to use the `EmailForm` schema:
.. code-block:: python
# in the controller
def email(self):
schema = EmailForm()
try:
form_result = schema.to_python(request.params)
except formencode.validators.Invalid, error:
return 'Invalid: %s' % error
else:
return 'Your email is: %s' % form_result.get('email')
If the values entered are valid, the schema's `to_python()` method returns a
dictionary of the validated and coerced `form_result`. This means that you can
guarantee that the `form_result` dictionary contains values that are valid and
correct Python objects for the data types desired.
In this case the email address is a string so `request.params['email']`
happens to be the same as `form_result['email']`. If our form contained a
field for age in years and we had used a `formencode.validators.Int()`
validator, the value in `form_result` for the age would also be the correct
type; in this case a Python integer.
FormEncode comes with a useful set of validators but you can also easily
create your own. If you do create your own validators you will find it very
useful that all FormEncode schemas' `.to_python()` methods take a second
argument named `state`. This means you can pass the Pylons `c` object
into your validators so that you can set any variables that your validators
need in order to validate a particular field as an attribute of the `c`
object. It can then be passed as the `c` object to the schema as follows:
.. code-block:: python
c.domain = 'example.com'
form_result = schema.to_python(request.params, c)
The schema passes `c` to each validator in turn so that you can do things like this:
.. code-block:: python
class SimpleEmail(formencode.validators.Email):
def _to_python(self, value, c):
if not value.endswith(c.domain):
raise formencode.validators.Invalid(
'Email addresses must end in: %s' % \
c.domain, value, c)
return formencode.validators.Email._to_python(self, value, c)
For this to work, make sure to change the `EmailForm` schema you've defined to use the new `SimpleEmail` validator. In other words,
.. code-block:: python
email = formencode.validators.Email(not_empty=True)
# becomes:
email = SimpleEmail(not_empty=True)
In reality the invalid error message we get if we don't enter a valid email address isn't very useful. We really want to be able to redisplay the form with the value entered and the error message produced. Replace the line:
.. code-block:: python
return 'Invalid: %s' % error
with the lines:
.. code-block:: python
c.form_result = error.value
c.form_errors = error.error_dict or {}
return render('/form.mako')
Now we will need to make some tweaks to `form.mako`. Make it look like this:
.. code-block:: html+mako
${h.form(h.url(action='email'), method='get')}
% if c.form_errors:
Please correct the errors
% else:
Enter Email Address
% endif
% if c.form_errors:
Email Address: ${h.text_field('email', value=c.form_result['email'] or '')}
${c.form_errors['email']}
% else:
Email Address: ${h.text_field('email')}
% endif
${h.submit('Submit')}
${h.end_form()}
Now when the form is invalid the `form.mako` template is re-rendered with the error messages.
Other Form Tools
================
If you are going to be creating a lot of forms you may wish to consider using `FormBuild `_ to help create your forms. To use it you create a custom Form object and use that object to build all your forms. You can then use the API to modify all aspects of the generation and use of all forms built with your custom Form by modifying its definition without any need to change the form templates.
Here is an one example of how you might use it in a controller to handle a form submission:
.. code-block:: python
# in the controller
def form(self):
results, errors, response = formbuild.handle(
schema=Schema(), # Your FormEncode schema for the form
# to be validated
template='form.mako', # The template containg the code
# that builds your form
form=Form # The FormBuild Form definition you wish to use
)
if response:
# The form validation failed so re-display
# the form with the auto-generted response
# containing submitted values and errors or
# do something with the errors
return response
else:
# The form validated, do something useful with results.
...
Full documentation of all features is available in the `FormBuild manual `_ which you should read before looking at `Using FormBuild in Pylons `_
Looking forward it is likely Pylons will soon be able to use the TurboGears widgets system which will probably become the recommended way to build forms in Pylons.