Stanford University Wiki

Platypus Forms

229pages on
this wiki
Add New Page
Talk0 Share


Every time a person signs up for a new service for on a website, fills out a survey or simply sends an email through a service like Gmail they have to fill out a form. To this day, basic forms remain the most prevalent method of interaction on the web. Instead of trying to invent a new form of data manipulation on the web page we decided to look into how to improve the flow of data entry through forms.

We looked at two aspects of form entry that we found lacking. First, there is usually no good description of why or how a particular piece of data is required by on a website. Second, we noticed that many forms were not actually a single step process. Rather they progress very much in a wizard like fashion. One reason for this would be to validate certain data before the next step is allowed. Another is to show only a part of the form at a time to reduce the cognitive load on the user. The downside to a lot of these step by step forms is that they don't include any indication of progress.

Aside from the end user facing changes, a major goal of Platypus Forms was to build a nice package for developers to use. The additions we made to forms would not be very valuable to the developer community without such packaging. In it's current iteration Platypus Forms is an extension to Django forms on the backend. One thing of note here is that since Platypus Forms deals with wizard like interactions it is not simply an extention of Django forms, it infact aggregates multiple forms within it. On the front end we provide a Javascript and CSS file developed on top of Prototype and Scriptaculous to be included in the pages containing the forms. The files are short and simple giving the front end developer ultimate flexibility in modifying the look and feel.

Description of the user interactionEdit

Picture 2

As described above there are two problems with the standard form of data entry with forms. First, there is not usually a description for a field, and if there is, it is in an incoveniently placed in the middle of the form flow. In Platypus Forms this is provided in a tooltip bubble that appears to the right of the field currently in focus. As focus is changed to a different form field, either by pressing tab or clicking on a different field, the tooltip changes accordingly to the currently highlighted form.

Second, many forms are multi-step processes. The reasons for this are outlined above. Platypus Forms provide a few improvements to work with multi-step forms. First it provides a simple progress bar indicating total work completed so far. Second it shows the user all the future steps in a grayed out box. These features give the user an indication of what is stil left and how far they've come in the process.

After each step is completed by the user, there are two things that can happen. If the step validates then the current step is whisked away to the left, the progress bar moves further and the next step becomes enabled and popped to the top. These few simple animations give the user a sense of progress generally making the cumbersome form filling a bit lighter. If the step does not validate then the errors are shown above each offending field.

Once the final step is completed the form submits as any normal web form (at least in the eyes of the user) and completes.

Architecture and implementationEdit

Django integrationEdit

The Platypus Forms framework is designed for easy integration with the popular Django web framework. Django already includes an efficient but basic forms framework, which follows the DRY principle and automatically generates form HTML and does form validation based on a Python description of a given web form.

We therefore decided to extend the Django forms framework, to allow web developers to use Platypus Forms with as little additional coding overhead as possible. Our GuidedForm class extends the Django Form class, essentially adding an as_div() method (similar to the existing as_p() and as_table() methods). This method generates the HTML for the form object, including any labels, error text and tool-tips that may be necessary.

Our other key new class is the GuidedFormGroup class, which is essentially an intelligent collection class which encapsulates an ordered list of GuidedForms. The ordering of this list represents the order in which the end-user must fill out each form. The class has two key functions:

  • render: generates the HTML corresponding to the entire group of forms.
  • partialFormAjaxSubmission: handles the AJAX calls made by the client after the completion of each component form, and performs form validation (either authorizing the client to move onto the next form, or responding with a JSON dictionary of field errors).

Since the GuidedFormGroup class must conserve state across multiple calls from the user, it stores itself in the Django session. In particular this requires the object and all its component data structures to be serializable.

Client-side operationsEdit

On the client-side, our Javascript file guidedForm.js takes care of displaying relevant tool-tips, submitting completed forms via AJAX and handling the response, and managing elements such as the progress bar and animations. Our code builds off of the popular Prototype and Scriptaculous libraries, which are therefore also required. As the Javascript file is static (and not dynamically generated by Django like the HTML files), it relies on conventions in naming the id and class attributes to identify relevant elements in the DOM at run-time.

In a nutshell, the Javascript tool-tips relies on focus events from the different form fields to know which field is currently being filled in, and therefore which tool-tip to display. The "greying out" of all forms after the current one is achieved by overlaying a semi-opaque div over each form, which is then hidden (in an animated fashion) when a given form becomes active. Form submission is handled entirely via AJAX calls (and then parsing out validation errors or commands), and not by the conventional HTML form POST mechanism.

guidedForm.css contains the CSS for the tool-tips, form hiding, the progress bar, etc. This file can be extended and modified by the developer to suit the look of their website. In tandem of the guidedForm.css, tooltip.gif is also required, this is the image of the tooltip bubble which appears to the right of the input elements.

Encapsulation and reusabilityEdit

We designed Platypus Forms from the ground up to be easy to reuse and to integrate well with the existing Django framework and web design patterns.

Usage requirementsEdit

Platypus Forms is extremely easy to use (although naturally it assumes that one is developing with Django). On the server-side, the user needs to pull in the Python files and She can define her application's forms in the conventional Django manner, using the optional help_text argument to specify the tool-tip text, e.g.:

   class EmailForm(GuidedForm):
       email = forms.EmailField(help_text='Use a real email address!')
       password = forms.CharField(max_length=50, widget=forms.PasswordInput(render_value=False), 
                                  help_text='Choose a password')

She can then specify form groups by simply giving a list of forms and the URL to call upon completion, e.g.

   formGroup = GuidedFormGroup([EmailForm, OtherForm, YetAnotherForm], 
                               '/completed/', request.session)

HTML generation in page templates is trivially achieved by calling {{ form.as_div }} or {{ form_group.render }} . Finally, the pages must also pull in the Prototype, Scriptaculous (with effects.js), guidedForm.js and guidedForm.css files.


We designed Platypus Forms to easily adapt to different designs and pre-existing Django projects. Since it extends in a backward-compatible fashion the Django forms framework, if a project already uses Django forms then Platypus Forms can be dropped in and used with pretty much no additional code.

From a design and styling perspective, all of the automatically generated HTML elements have intuitive class and id attributes, so the generated forms can easily be styled with CSS.


Platypus Forms should be easy to modify or extend with new features. Indeed, pretty much any extension to Django forms could be applied directly to Platypus Forms by subclassing GuidedForm instead of Form. On the client-side, the footprint of our Javascript and CSS is fairly minimal.



There are many strengths of Platypus Forms. For the user Platypus Forms provides clear indication of progress in a multi-step data entry process. It also allows the developer to help the user out further by providing descriptive tooltips for each form input element.

On the developer side is where Platypus Forms truly shines. As described above Platypus Forms integrates seamlessly with built in forms provided by Django reusing much of it's facilities such a form validation and element rendering. In particular the ability to package multiple forms in a step by step process is what allows Platypus Forms to be increadibly useful to developers.

Platypus Form package also validates on the server using AJAX form submission as done in FIZ. This is allows all validation code to reiside entirely on the server without causing a refresh of the page. Another advantage of this is that the user does not loose their position in the page and more importantly in the form steps every time the move forward.


In it's default implementation Platypus Forms shows all the future steps in a grayed out area below the current step. This is there to give the user an indication of what is left to be done. However, this very hint could be frustrating to the user for a flow that is not well thought out. If for example there are simple one button responses to each step in the form flow, then it could be frustrating to see that there are so many of them that need to be moved through. This however can be customized by the developer. Simple modifications to the provided Javascript and CSS can hide future steps allowing for a familiar wizard like interaction.

Since Platypus Forms extends Django Forms it inherits all of it's strengths and weaknesses. In particular Djano Forms don't natively support more exotic form entry mechanisms (Calendar Date Pikers etc.) that have become more common place on the web. However, since the Django community is large and growing as more extentions to Django Forms are made those will automatically carry over to Platypus Forms.

There are other weaknesses to Platypus Forms that are simply limitations that could be compensated for in future extensions.


Since the Platypus Form package is young there are various improvements and extensions that can be made for it.

One of the most interesting possible extensions would be to have the flow of forms be based on a decision tree rather than the linear flow that exists now. For example this would allow diferent steps to appear after a user has chosen their gender. Such a flow would generalize Platypus Forms enough so that it would be widely adopted by developers.

A limitation of Ajax form submission is that it does not allow for file uploads, this must be handled either by a traditional form submission or a form submission into a hidden iframe. Since Platypus Forms currently uses Ajax form submission exclusively, an important extension to Platypus Forms would be to allow file uploads in form flow.


Overall Platypus Forms allows for quickly implementing a multi-step form entry process for the web. It adheres to the DRY principle upheald by Django and asks the developer to simply specify the form and flow once. Once polished further it can be released to the Django community at large for further use and development.

Ad blocker interference detected!

Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.