Form Processing with Flatland
For the past three months at work we've been using Jason Kirtland's Flatland form processing library for HTML form definition and validation. We recently had a sprint (along with Michel Pelletier and Ben Stover) to head towards a release. One thing remaining is to spruce up the docs; I thought I'd write up a little introduction here as a part of that effort.
While code is the easiest way to explain using Flatland, it's important to start with understanding that Flatland has two main sets of objects that work together, schema objects and element objects. Schema objects represent the hierarchical data model your application uses, and element objects are a real instantiation of that schema with data.
If you've used Django's forms or WTForms the basic structure will be familiar.
import flatland
class CommentForm(flatland.Form):
schema = [
flatland.String('name', label='Your Name', default='Anonymous'),
flatland.String('email', label='Your Email Address',
validators=[flatland.valid.email.IsEmail()]),
flatland.String('comment', label='Your comment'),
]
Using the form in a view/controller is straightforward (in this example, request is a werkzeug.Request object).
def new_comment(request):
if request.method == 'POST':
form = CommentForm.from_flat(request.form)
if form.validate():
name = form.el('name').u
comment = form.el('comment').u
# Do comment saving stuff
...
else:
form = CommentForm.from_defaults()
# Template rendering, etc...
One note: the IsEmail validator was added in the spring, and hasn't made it in to the main branch yet. It will be soon, and will be in the first release.
Most form libraries have either methods to convert to HTML input elements or corresponding widget objects, but Flatland is display agnostic. Included in the library is a set of output handlers for the Genshi template language, and there's some initial support for Jinja2 soon. In any case rendering is a bit more explicit than with other libraries, which in practice has not been a problem at all for us.
Now this is all fine and dandy, but it doesn't really justify a different library, perhaps. Where Flatland really shines, however, is in hierarchical data models with multiple validation levels. For example:
class ProfileForm(flatland.Form):
schema = [
flatland.String('name', label='Your Name',
validators=[flatland.valid.Present()]),
flatland.List('emails',
flatland.String('email', validators=[flatland.valid.email.IsEmail()]),
label='Contact Email Addresses'),
]
form = ProfileForm.from_flat([
(u'name', u'Me!'),
(u'emails_0_email', u'bob@bob.bob'),
(u'emails_1_email', u'foo@bar.baz'),
]
form.validate() # True
form.el('emails').value # [u'bob@bob.bob', u'foo@bar.baz']
The same schema could be used to validate a JSON request.
import simplejson
input = simplejson.loads(
'{"name": "Me!", "emails": ["bob@bob.bob", "noone@example.com"]}')
form = ProfileForm.from_value(input)
form.validate() # True
form.el('emails').value # [u'bob@bob.bob', u'noone@example.com']
For one last, more complex example, here is a custom schema and element for using the VidoopCAPTCHA:
vs = vidoopsecure.VidoopSecure(settings.VS_API_USER, settings.VS_API_PASS,
settings.VS_CUSTOMER_ID, settings.VS_SITE_ID)
class VSCaptchaElement(flatland.schema.containers._DictElement):
"""Flatland element for captchas. Knows how to fetch a new captcha."""
url = None
categories = None
def set_default(self):
"""Get a new VS captcha and fill our needed data values."""
captcha_id, captcha_url, captcha_categories = vs.create_captcha(
order_matters=False, width=3, height=3, image_code_color='White')
self.el('id').set(captcha_id)
self.url = captcha_url
self.categories = captcha_categories
class VSCaptchaField(flatland.schema.containers.Dict):
"""Field that starts and validates a Vidoop Secure CAPTCHA"""
element_type = VSCaptchaElement
def __init__(self, name='vscaptcha', **kw):
fields = [
flatland.String("code"),
flatland.String("id"),
]
super(VSCaptchaField, self).__init__(name, *fields, **kw)
def validate_element(self, element, state, descending):
if descending:
return None
if not element.el('code').value:
element.errors.append("This CAPTCHA code may not be blank.")
return False
try:
success = vs.submit_captcha(element.el('id').u, element.el('code').u)
return success is True
except vidoopsecure.CaptchaAlreadyTried:
element.errors.append("This CAPTCHA has aready beeen attempted. "
"Try clicking your browser's refresh button.")
except vidoopsecure.CaptchaExpired:
element.errors.append("This CAPTCHA expired. "
"Try clicking your browser's refresh button.")
except vidoopsecure.CaptchaFailed:
element.errors.append('Sorry, you entered the wrong code. '
'Please try again.')
return False
I've been extremely impressed with Flatland so far. While there's still work to be done fleshing out the standard fields, validators, and docs, the code base is heavily tested and and a pleasure to work with. Hopefully there will be a release soon; in the meantime check out the code on Bitbucket.
Updated 2008-02-24 10:21: Fixed typos