14.6 Form processing

There are many ways to display and process HTML forms with Cheetah. But basically, all form processing involves two steps.

Display the form.
In the next web request, read the parameters the user submitted, check for user errors, perform any side effects (e.g., reading/writing a database or session data) and present the user an HTML response or another form.

The second step may involve choosing between several templates to fill (or several servlets to redirect to), or a big if-elif-elif-else construct to display a different portion of the template depending on the situation.

In the oldest web applications, step 1 and step 2 were handled by separate objects. Step 1 was a static HTML file, and step 2 was a CGI script. Frequently, a better strategy is to have a single servlet handle both steps. That way, the servlet has better control over the entire situation, and if the user submits unacceptable data, the servlet can redisplay the form with a "try again" error message at the top and and all the previous input filled in. The servlet can use the presence or absence of certain CGI parameters (e.g., the submit button, or a hidden mode field) to determine which step to take.

One neat way to build a servlet that can handle both the form displaying and form processing is like this:

Put your form HTML into an ordinary template-servlet. In each input field, use a placeholder for the value of the VALUE= attribue. Place another placeholder next to each field, for that field's error message.
Above the form, put a $processFormData method call.
Define that method in a Python class your template #extends. (Or if it's a simple method, you can define it in a #def.) The method should:
1. Get the form input if any.
2. If the input variable corresponding to the submit field is empty, there is no form input, so we're showing the form for the first time. Initialize all VALUE= variables to their default value (usually ""), and all error variables to "". Return "", which will be the value for $processFormData.
3. If the submit variable is not empty, fill the VALUE= variables with the input data the user just submitted.
4. Now check the input for errors and put error messages in the error placeholders.
5. If there were any user errors, return a general error message string; this will be the value for $processFormData.
6. If there were no errors, do whatever the form's job is (e.g., update a database) and return a success message; this will be the value for $processFormData.
The top of the page will show your success/failure message (or nothing the first time around), with the form below. If there are errors, the user will have a chance to correct them. After a successful submit, the form will appear again, so the user can either review their entry, or change it and submit it again. Depending on the application, this may make the servlet update the same database record again, or it may generate a new record.

FunFormKit is a third-party Webware package that makes it easier to produce forms and handle their logic. It has been successfully been used with Cheetah. You can download FunFormKit from http://colorstudy.net/software/funformkit/ and try it out for yourself.