The Basics

When a user submits a form on a website the data is submitted to the URL specified in the action attribute of the <form> tag. The data can be submitted either via HTTP GET or POST as specified by the method attribute of the <form> tag. If your form doesn't specify an action, then it's submitted to the current URL, generally you'll want to specify an action. When a file upload field such as <input type="file" name="file" /> is present, then the HTML <form> tag must also specify enctype="multipart/form-data" and method must be POST.

Getting Started

First install Pylons and follow the Getting Started Guide so that you have a running HelloWorld application with a hello controller available at http://localhost:5000/hello served with the --reload option.

Add two actions that looks like this:

1
2
3
4
5
6
7

# in the controller

    def form(self):
        return render('/form.mako')

    def email(self):
        return 'Your email is: %s' % request.params['email']

Add a new template called form.mako in the templates directory that contains the following:

1
2
3
4

<form name="test" method="GET" action="/hello/email">
Email Address: <input type="text" name="email" />
               <input type="submit" name="submit" value="Submit" />
</form>

If the server is still running (see the Getting Started Guide) you can visit http://localhost:5000/hello/form and you will see the form. Try entering the email address test@example.com and clicking Submit. The URL should change to http://localhost:5000/hello/email?email=test%40example.com and you should see the text Your email is test@example.com.

In Pylons all form variables can be accessed from the request.params object which behaves like a dictionary. The keys are the names of the fields in the form and the value is a string with all the characters entity decoded. For example note how the @ character was converted by the browser to %40 in the URL and was converted back ready for use in request.params.

If you have two fields with the same name in the form then using the dictionary interface will return the first string. You can get all the strings returned as a list by using the .getall() method. If you only expect one value and want to enforce this you should use .getone() which raises an error if more than one value with the same name is submitted.

By default if a field is submitted without a value, the dictionary interface returns an empty string. This means that using .get(key, default) on request.params will only return a default if the value was not present in the form.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# in the controller

    def form(self):
        return render('/form.mako')

    def email(self):
        # Code to perform some action based on the form data
        # ...
        redirect_to(action='result')

    def result(self):
        return 'Your data was successfully submitted'

Using the Helpers

Creating forms can also be done using Pylons' built in helpers. Here is the same form created in the previous section but this time using the helpers:

1
2
3
4

${h.form(h.url(action='email'), method='get')}
Email Address: ${h.text_field('email')}
               ${h.submit('Submit')}
${h.end_form()}

You can also make use of the built-in script.aculo.us functionality or override the default behavior of any of the helpers by defining a new function of the same name at the bottom of your project's lib/helpers.py file.

File Uploads

File upload fields are created by using the file input field type. The file_field helper provides a shortcut for creating these form fields:

1

${h.file_field('myfile')}

The HTML form must have its enctype attribute set to multipart/form-data to enable the browser to upload the file. The form helper's multipart keyword argument provides a shortcut for setting the appropriate enctype value:

1
2
3
4
5

${h.form(h.url(action='upload'), multipart=True)}
Upload file:      ${h.file_field('myfile')} <br />
File description: ${h.text_field('description')} <br />
                  ${h.submit('Submit')}
${h.end_form()}

When a file upload has succeeded, the request.POST (or request.params) MultiDict will contain a cgi.FieldStorage object as the value of the field.

FieldStorage objects have three important attributes for file uploads:

filename

The name of file uploaded as it appeared on the uploader's filesystem.

file

A file(-like) object from which the file's data can be read: a python tempfile object.

value

The content of the uploaded file, eagerly read directly from the file object.

The easiest way to gain access to the file's data is via the value attribute: it returns the entire contents of the file as a string:

1
2
3
4

def upload(self):
    myfile = request.POST['myfile']
    return 'Successfully uploaded: %s, size: %i, description: %s' % \
        (myfile.filename, len(myfile.value), request.POST['description'])

However reading the entire contents of the file into memory is undesirable, especially for large file uploads. A common means of handling file uploads is to store the file somewhere on the filesystem. The FieldStorage instance already reads the file onto filesystem, however to a non permanent location, via a python tempfile object.

Python tempfiles are secure file objects that are automatically destroyed when they are closed (including an implicit close when the object is garbage collected). One of their security features is that their path cannot be determined: a simple os.rename from the tempfile's path isn't possible. Alternatively, shutil.copyfileobj can perform an efficient copy of the file's data to a permanent location:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

permanent_store = '/uploads/'

class Uploader(BaseController):
    def upload(self):
        myfile = request.POST['myfile']
        permanent_file = open(os.path.join(permanent_store,
                                           myfile.filename.lstrip(os.sep)),
                                                               'w')

        shutil.copyfileobj(myfile.file, permanent_file)
        myfile.file.close()
        permanent_file.close()

        return 'Successfully uploaded: %s, description: %s' % \
            (myfile.filename, request.POST['description'])

Validation the Quick Way

At the moment you could enter any value into the form and it would be displayed in the message, even if it wasn't a valid email address. In most cases this isn't acceptable since the user's input needs validating. The recommended tool for validating forms in Pylons is FormEncode.

For each form you create you also create a validation schema. In our case this is fairly easy:

1
2
3
4
5
6

import formencode

class EmailForm(formencode.Schema):
    allow_extra_fields = True
    filter_extra_fields = True
    email = formencode.validators.Email(not_empty=True)

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, imported by default in your lib/base.py. Using it in your controller is pretty straight-forward:

1
2
3
4
5
6
7
8

# 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:

1

${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.

Validation the Long Way

The validate decorator covers up a bit of work, and depending on your needs its possible you could need direct access to FormEncode abilities it smoothes over.

Here's the longer way to use the EmailForm schema:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 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.

1
2

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:

1
2
3
4
5
6

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,

1
2
3

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:

1

return 'Invalid: %s' % error

with the lines:

1
2
3

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

${h.form(h.url(action='email'), method='get')}

% if c.form_errors:
<h2>Please correct the errors</h2>
% else:
<h2>Enter Email Address</h2>
% endif

% if c.form_errors:
Email Address: ${h.text_field('email', value=c.form_result['email'] or '')}
<p>${c.form_errors['email']}</p>
% 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 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.