Mosaic for X "Level 2" Fill-Out Form Support

Here are details about what we have implemented as "level 2" (third cut) for fill-out forms in Mosaic for X 2.0, prerelease 6 -- this is based on the current HTML+ spec with a few changes. Be sure you have prerelease 6, else many of the details herein will be wrong.

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:

ACTION is the URL to which the query string (see below) is appended when the form is filled out; if this attribute is absent, then the current document URL will be used.

Inside a FORM you can have anything except another FORM. Specifically, INPUT and SELECT tags are used to specify interface elements for 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 surround 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:

TYPE must be one of:
- "text" (text entry field; this is the default)
- "password" (text entry field; entered characters are represented as asterisks)
- "checkbox" (a single toggle button; on or off)
- "radio" (a single toggle button; on or off; other toggles with the same NAME are grouped into "one of many" behavior)
- "submit" (a pushbutton that causes the current form to be packaged up into a query URL and sent to a remote server)
- "reset" (a pushbutton that causes the various input elements in the form to be reset to their default values)
NAME is the symbolic name (not a displayed name -- normal HTML within the form is used for that) for this input field. This must be present for all types but "submit" and "reset", as it is used when putting together the query string that gets sent to the remote server when the filled-out form is submitted.
VALUE, for a text or password entry field, can be used to specify the default contents of the field. For a checkbox or a radio button, VALUE specifies the value of the button when it is checked (unchecked checkboxes are disregarded when submitting queries); the default value for a checkbox or radio button is "on". For types "submit" and "reset", VALUE can be used to specify the label for the pushbutton.
CHECKED (no value needed) specifies that this checkbox or radio button is checked by default; this is only appropriate for checkboxes and radio buttons.
SIZE is the physical size of the input field in characters; this is only appropriate for text entry fields and password entry fields. If this is not present, the default is 20. Multiline text entry fields can be specified as SIZE=width,height; e.g. SIZE=60,12.
MAXLENGTH is the maximum number of characters that are accepted as input; this is only appropriate for text entry fields and password entry fields (and only for single-line text entry fields). If this is not present, the default will be unlimited. The text entry field is assumed to scroll appropriately if MAXLENGTH is greater than SIZE.

The SELECT Tag

Inside <FORM> ... </FORM>, any number of SELECT tags are allowed, freely intermixed with other HTML elements (including INPUT elements; see above) 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:

        <SELECT NAME="a-menu">
        <OPTION> First option.
        <OPTION> Second option.
        </SELECT>

The attributes to SELECT are as follows:

NAME is the symbolic name for this SELECT. This must be present, as it is used when putting together the query string.
SIZE: if SIZE is 1 or if the SIZE attribute is missing, by default the SELECT will be represented as a Motif option menu. If SIZE is 2 or more, the SELECT will be represented as a Motif scrolled list; the value of SIZE then determines how many items will be visible.
MULTIPLE, if present (no value), specifies that the SELECT should allow multiple selections (n of many behavior). The presence of MULTIPLE forces the SELECT to be represented as a Motif scrolled list, regardless of the value of SIZE.

The attributes to OPTION are as follows:

SELECTED specifies that this option is selected by default. If the SELECT allows multiple selections (via the MULTIPLE attribute), multiple options can be specified as SELECTED.

Form Submission

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.

Things To Note

Lots of things actually in the HTML+ spec aren't yet supported. In particular, mailto: URLs aren't supported as actions yet, and also the "level 2" support only includes a subset of the allowable types of input fields (obviously "text" can also serve as "url", "int", "float", and "date" but without intrinsic range/error checking).
The HTML+ spec says "The Return key can be used to mean the user has filled in the form and wants the appropriate action to be taken." We don't, in general, like that, because:
- It is bad interface design to have a Return keystroke in any of several text entry fields cause the entire form to be submitted; users will hit Return inadvertently before they have filled out the entire form and the interface should protect them from that. (C.f. AIX SMIT.)
- Some forms will not have any text entry fields, and it is not obvious how submission is supposed to be handled then (where should the pointer be? what if there are multiple forms in the same visible window? etc.).
Therefore we support INPUT tags of TYPE "submit"; each instance of such a tag causes a pushbutton to be created that causes the form to be submitted when it's pressed. Multiple submit buttons can be present in a single form; the label of each button can be controlled via the VALUE attribute.
(The exception to the above is forms containing only a single text field; in that case, Return in the text field will cause the query to be submitted. Submit buttons are also supported in forms containing only a single text field.)
We also support INPUT tags of TYPE "reset", which allow the form input elements to be reset to their default values. This type of input field is otherwise handled the same as "submit".

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.

Justification for change:

Consistent approach to query mechanisms inside Mosaic.
Allow code and interface complexity to be reduced.
A few nasty problems were hitting the "popup text entry field" approach attempted for prerelease 2; notably, lots of unavoidable flashing when field popped up and down and intermittent but crippling Motif geometry management problem. This change removes those problems.
Everyone wants the ability to enter a query (and the corresponding widgets) to be present only when the document is actually an ISINDEX document; this provides that very cleanly.
This solves existing problem of when to retain contents of search field -- since search field now exists on a per-document basis, this is very clean.
Encourage experimentation with fill-out forms by presenting an example for existing query engines.

Examples

Eleven examples are available; you will need to be running Mosaic 2.0 prerelease 6 or later to actually have them show up as forms, but you can examine the raw HTML with earlier versions or other browsers:

Example 1 -- a ludicrously simple fill-out form.
Example 2 -- three text entry fields.
Example 3 -- text entry fields and toggle buttons.
Example 4 -- changing the default values of text entry fields and toggle buttons.
Example 5 -- changing various attributes of text entry fields.
Example 6 -- multiple, independent forms in a single document.
Example 7 -- radio buttons, "one of many" behavior.
Example 8 -- password entry fields.
Example 9 -- option menus.
Example 10 -- scrolled lists with single and multiple selections.
Example 11 -- multiline text entry areas.

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.

Comments?

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