Illustration by ZopeMag Staff

Formulator

	Product name Formulator Description A Zope product that eases the creation and validation of web forms Release Date 2003/08/13 Version 1.5.0 (Stable) Rating (all ratings are on scale of 1-5 with 5 sushi being the best) Usability Software Design Documentation Usefulness Categories Web Forms framework Size 67.8 Kbytes Requirements Zope 2.5 or higher Creator Martijn Faassen License ZPL URL Download Packaged as Zope Product

Simplifies the design and validation of Web forms. Allows the programmer to concentrate on the layout of the form, as well as on the processing and validation of the data, rather than on the rendering of the form.

It does not work as well as desired with Zope Page Templates—although there have been a lot of improvements in recent versions.

Web forms are among the most useful features of HTML. They allow us to collect remote input from HTML documents that have blanks that can be filled in by the user. For example, they enable us to get feedback from our Website's visitors through customized polls and surveys, or to create queries that can be used to update a database or to feed a program or script. Additionally, they are relatively easy to create and use.

Nonetheless, despite their apparent simplicity, web forms can be tricky and risky. For example, although HTML specifies several field types (in HTML they are called “control types”) that can be used in a web form, none of these field types says anything about the type of data the field itself contains - which in all cases is considered as a string. The immediate effect of this lack of consistency in data type definition is a greater possibility of failure when parameters are passed to a script or a program—which requires additional lines of code to validate the type of data passed by the form. Zope tries to cope with this by specifying type converters which are embedded into the HTML field declaration. As Zopists know very well, these converters help programmers to catch conversion errors but, at the same time, can complicate the definition of a web form. In addition to knowing the HTML specification of a web form, now the programmer needs to know what type of converter to use, and to specify a converter for very “control type” used in the form (this is good programming practice).

Originally developed by Martijn Faassen Formulator simplifies the creation of web forms to be used with Zope applications. Additionally, this product takes care of both the rendering of the fields and the validation of the data passed by the form. Formulator uses Zope's converters too, but in such a way that their use is completely hidden from the programmer. When the programmer chooses a “control type” from th elist offered by Formulator the converter is implicitly embedded in the control type. Nevertheless, Formulator does not specify the exact layout of the form—which continues to be within the scope of the programmer's taste.

Formulator is very easy to install. In most cases, it comes in a compressed TAR file that can be installed in Zope's Products folder (/lib/python/Products). The file can be downloaded from here. Once downloaded, one can use the standard UNIX command

tar -xvf

to decompress the package within the Products folder. It is important not to forget to check if the product has been appropriately installed. Go to the ZMI and check the Products folder within the Control_Panel. If Formulator was appropriately installed, it should appear as in Figure 1.

Figure 1 - Installled Product Formulator

To create a new Formulator form, one just needs to create a new folder and then pick a Formulator form object from the Add list and add it to the folder. In our example, we created a businessCardBuilder folder and added a bizCard form to it. Figure 2 shows the content of the /businessCardBuilder/bizCard object and Figure 6 shows what the business card looks like on rendering.

Figure 2 - Contents of Bizcard Object

As one can see from the figure, the Formulator object has several other views, in addition to the Content view itself. In the Test view we can test our form with sample data. The Order view allows us re-order our fields as they are rendered by Formulator—for instance, rendering the LastName field before the firstName field or vice versa. Also, the Order view enables us to group our fields.

The Settings view allows us to configure certain important properties required by the HTML specification. Those properties are: the method used by the client (browser) to pass the data (POST or GET), the path of the script or method responsible for the processing of the data, and the enclosure type. Figure 3 shows the Settings view used in our example.

Figure 3 - Settings View

The XML view shows the XML representation of our form. The XML representation may be useful for duplicating this form in a different application later on. The rest of the views are common to most Zope products so our reader should be familiar with them.

A closer examination of Figure 2 shows that the Content view contains a pop-down list box. As you can see from Figure 4, adding a new field to our form can be as simple as picking an object from the list and then pressing the Add button. Immediately, a new screen appears asking us to introduce the id and Title for the new field. Once this information has been entered and the “Add and Edit” button has been clicked, a new view appears.

Figure 4 - Adding a new field

Figure 5 shows the Edit view, immediately after one presses “Add and Edit”, with the Widget Properties required by the field firstName. This view shows all the attributes specified by the HTML protocol for this particular type of field. Additionally, in this view one can also specify the parameters used by the validator method. The DTML method or script that is specified in the Action property (as specified by HTML) processes the form and generates the appropriate error messages. All data is passed by a REQUEST object, keyed under the field's id.

Figure 5 - Edit View

It is important to note that a validator should do at least three things (which are provided by Formulator). On the one hand, it should validate all fields to guarantee every one of them to be consistent. Secondly, it should catch any error that might result from the validation process. Finally, it should process the form if no error is found.

Another important feature of Formulator is its ability to use external methods (e.g., Python scripts) to override the property value in a field. When the property value in the Edit view is used, the external method with the name listed in the Override view will be called to retrieve a value instead of the original property value.

As mentioned above, Figure 6 shows the completed sample web form. The form was generated using the Test view.

Figure 6 - Form generated by Test View

Formulator can be used with both DTML methods and page templates. Using DTML is straightforward. Additional information may be found in the Formulator's How-To.

Using ZPT requires some extra work. An interesting review of how to do it may be found in the following Zope Labs cookbook Recipe

Formulator is a very simple and powerful tool for creating and validating web forms within Zope. It hides much of the complexity of using web forms in Zope, such as type conversion and validation. Forms can be easily created through the Zope Management Interface. Validation routines can be provided through DTML methods or external methods.