Mosaic for X version 2.0 Fill-Out Form Support

Here are details about what we have implemented for fill-out forms in Mosaic for X 2.0.

The FORM Tag

The FORM tag specifies a fill-out form within an HTML document. More than one fill-out form can be in a single document, but forms cannot be nested.

<FORM ACTION="url"> ... </FORM>

The attributes are as follows:

NOTE: If you want to use the METHOD of type POST with the NCSA httpd you will need to get version 1.0a5 or later.

Inside a FORM you can have anything except another FORM. Specifically, INPUT, SELECT, and TEXTAREA tags are used to specify interface elements within the form.

Forms are not automatically visually differentiated from the rest of a document. We recommend using the HR (horizontal rule) tag before and after a form to cleanly differentiate it from surrounding text and/or other forms.

The INPUT Tag

The INPUT tag is used to specify a simple input element inside a FORM. It is a standalone tag; it does not surround anything and there is no terminating tag -- i.e., it is used in much the same way as IMG.

In Mosaic for X, various types of INPUT tags are instantiated as Motif widgets (text entry fields, toggle buttons, pushbuttons, etc.).

The attributes to INPUT are as follows:

The SELECT Tag

Inside <FORM> ... </FORM>, any number of SELECT tags are allowed, freely intermixed with other HTML elements (including INPUT and TEXTAREA elements) and text (but not additional forms). In Mosaic for X, SELECT tags are instantiated as Motif option menus and scrolled lists.

Unlike INPUT, SELECT has both opening and closing tags. Inside SELECT, only a sequence of OPTION tags -- each followed by an arbitrary amount of plain text (no HTML markup) -- is allowed; for example:

        <SELECT NAME="a-menu">
        <OPTION> First option.
        <OPTION> Second option.
        </SELECT>
The attributes to SELECT are as follows:

The attributes to OPTION are as follows:

The TEXTAREA Tag

The TEXTAREA tag can be used to place a multiline text entry field with optional default contents in a fill-out form. The attributes to TEXTAREA are as follows:

TEXTAREA fields automatically have scrollbars; any amount of text can be entered in them.

The TEXTAREA element requires both an opening and a closing tag. A TEXTAREA with no default contents looks like this:

        <TEXTAREA NAME="foo" ROWS=4 COLS=40></TEXTAREA>
A TEXTAREA with default contents looks like this:

        <TEXTAREA NAME="foo" ROWS=4 COLS=40>
        Default contents go here.
        </TEXTAREA>
The default contents must be straight ASCII text. Newlines are respected (so in the above example there will be a newline both before and after "Default contents go here.").

Form Submission

For Method = GET

When the submit button is pressed, the contents of the form will be assembled into a query URL that looks like this:

    action?name=value&name=value&name=value
("action" here is the URL specified by the ACTION attribute to the FORM tag, or the current document URL if no ACTION attribute was specified.)

Strange characters in any of the "name" or "value" instances will be escaped as usual; this includes "=" and "&". Note: This means that instances of "=" that separate names and values, and instances of "&" that separate name/value pairs, are not escaped.

For text and password entry fields, whatever the user typed in will be the value; if the user didn't type anything, the value will be empty but the "name=" part of the query string will still be present.

For checkboxes and radio buttons, the VALUE attribute specifies the value of a checkbox or radio button when it is checked. An unchecked checkbox is disregarded completely when assembling the query string. Multiple checkboxes can have the same NAME (and different VALUEs), if desired. Multiple radio buttons intended to have "one of many" behavior should have the same NAME and different VALUEs.

For Method = POST

The contents of the form are encoded exactly as with the GET method (above), but rather than appending them to the URL specified by the form's ACTION attribute as a query, the contents are sent in a data block as part of the POST operation. The ACTION attribute (if any) is the URL to which the data block is POSTed.

Test Servers

If you wish to write a prototype fill-out form and test it against a query server that simply shows you what you submitted (with name/value pairs decoded and itemized), you can use the following:

The fill-out form examples listed below use these query servers as their back ends, so you can see them in action and know what to expect with your own forms.

Important note: If you use the GET method in your form, you will notice that the example GET server will choke if too much data (more than a couple hundred bytes) is submitted at a time -- the server is passing the data to the form-processing module via a shell command line, and the maximum shell command line length is being exceeded. This problem does not exist with the POST method and server.

Things To Note

ISINDEX Handling

Now that we have this fancy fill-out form support, we're supporting the ISINDEX tag differently. Instead of having a browser-interface method (dialog box or text field) for entering a query, an instance of ISINDEX is instantiated as a preloaded fill-out form suitable for entering a query; the form is inlined at the location of the ISINDEX tag itself in the document.

Justifications for change:

Examples

Twelve examples are available. All of the examples now use METHOD=POST.

Writing Your Own Fill-Out Form Query Engine

If you want to set up one or more query engines corresponding to fill-out forms that you create for database accesses or other purposes, you may want to take a look at NCSA httpd 1.0. One of the example programs included with NCSA httpd is a sample fill-out form server (the same server used in the examples above, actually) and will provide a good model for writing your own servers.

We strongly, strongly recommend use of the POST method with fill-out forms. One reason: with the GET method, given the way many servers (e.g. NCSA httpd) pass query strings from URLs to query server scripts, you run an excellent chance of having the forms contents truncated by hardcoded shell command argument lengths. With POST (again, e.g., with NCSA httpd) you should be able to do a total end run around such problems.

NCSA httpd 1.0 (the official release) should be out shortly and will contain an example POST fill-out form server.

Fill-Out Forms in the Real World

Here are some fill-out forms in use in the Real World(tm). For up-to-date examples, search on "form" in What's New.

Comments?

Please send mail to mosaic-x@ncsa.uiuc.edu.