Director CGI

Purpose

This CGI program allows web authors to create forms containing menus of choices which will determine which page the user will see next. For example, rather than having to create a list of links such as the following:

You can instead create a form like the one below:

The HTML is not any easier for the author to create (although it is not very much more difficult), but it does provide a somewhat cleaner interface for the user. The page should be less cluttered by repetitive text, and thus easier to read (which may even make it more likely to be read).

How Does It Work?

The Director CGI works in a way not too different from a server-side image map. The HTML of the page contains a form, which can contain any number of multiple-choice fields and one submit button. There is an auxilliary file (like the image map's map file) which contains the URLs of the destinations and values to match against the values the user selects from the form. There is one URL per line. The Director CGI scans through this file, and redirects the browser to the URL on the first line whose values match those on the form that the user submitted.

So, in the example above, the form looks roughly like this (some formatting information omitted for the sake of clarity):

<FORM METHOD="POST"
ACTION="http://www.lehigh.edu/cgi-bin/director/~inwww/director.ctrl">
    I am a(n):
    <SELECT
        NAME="status" SIZE=1>
        <OPTION VALUE="s0" SELECTED> (Select a category)        
        <OPTION VALUE="s1"> Prospective student.        
        <OPTION VALUE="s2"> Undergraduate student.        
        <OPTION VALUE="s3"> Graduate student.        
        <OPTION VALUE="s4"> Faculty or Staff.        
        <OPTION VALUE="s5"> Alumnus or Alumna.        
        </SELECT>    
    And I am (or wish to be) in the:    
    <SELECT
        NAME="college" SIZE=1>
        <OPTION VALUE="c0" SELECTED> (Select a college)        
        <OPTION VALUE="c1"> College of Arts and Sciences.        
        <OPTION VALUE="c2"> College of Engineering.        
        <OPTION VALUE="c3"> College of Business.        
        <OPTION VALUE="c4"> College of Education.        
        </SELECT>        
    <INPUT TYPE="SUBMIT" VALUE="Show Me The Information">
    </FORM>

And the corresponding control file (named "director.ctrl", as indicated in the HTML above) is:

/~inwww/director/examples/as-pstud.html s1 c1
/~inwww/director/examples/as-ustud.html s2 c1
/~inwww/director/examples/as-gstud.html s3 c1
/~inwww/director/examples/as-facst.html s4 c1
/~inwww/director/examples/en-pstud.html s1 c2
/~inwww/director/examples/en-ustud.html s2 c2
/~inwww/director/examples/en-gstud.html s3 c2
/~inwww/director/examples/en-facst.html s4 c2
/~inwww/director/examples/bu-pstud.html s1 c3
/~inwww/director/examples/bu-ustud.html s2 c3
/~inwww/director/examples/bu-gstud.html s3 c3
/~inwww/director/examples/bu-facst.html s4 c3
/~inwww/director/examples/ed-pstud.html s1 c4
/~inwww/director/examples/ed-gstud.html s3 c4
/~inwww/director/examples/ed-facst.html s4 c4
/~inwww/director/examples/alumnus.html  s5 

So, If the user selects "Prospective Student" and "College of Education" (corresponding to form values "s1" and "c4"), the Director CGI will redirect to the URL /~inwww/director/examples/ed-pstud.html.

Details

The Form

To use Director, you must create an HTML form. There are two required attributes which must be specified on the FORM tag, as shown in the example above. The METHOD must be specified as "POST" (this specifies the type of HTTP request that is made when the form is submitted; the default METHOD, if unspecified, is "GET"). The ACTION attribute, which specifies the URL of the CGI program which will handle the results of form submission, must be:

"http://www.lehigh.edu/cgi-bin/director/control-file-url"

The form can contain any number of fields. All of the fields should be multiple-choice fields of a "select one-from-many" type. This includes radio buttons (the INPUT element with TYPE="RADIO") and pop-up menus and scrolling lists (which both use the SELECT element; with SIZE="1" for pop-up menus and SIZE="n" for a scrolling list with n items visible at a time). The MULTIPLE attribute of the SELECT element should be avoided, and a default item should always be indicated (using the CHECKED attribute for radio buttons, or the SELECTED attribute for pop-ups and scrolling lists).

If there is only one choice field, the effect is as if it were a simple menu, like a list of links. With two fields, as in the example above, the effect is more like a two-way table of links. Although there is no real limit on how many choice fields you can have, be aware that the number of possible destinations increases rapidly as you add fields. For example, if you have four choice fields with only three choices each, you have eighty-one possible destinations (these do not all have to be different, but if the user chooses a combination which has no destination specified, an error message will result).

The names of the fields are irrelevant (at least insofar as Director is concerned): values are matched left-to-right in the control file lines and one-at-a-time in the order they are returned from the form (which should be identical with the order in which they are defined in the HTML source). In the example above, "status" is the name of the first field, and "college" is the name of the second; but these could have been named anything at all. The match will still be first value on the line (after the URL) against the first field ("status") and the second value on the line against the second field ("college").

The field values are only restricted in that they must not contain whitespace characters (each value must appear as a separate "word" on the control file line). However, since the user never sees the actual value (they only see the label), the value itself can be completely arbitrary. Notice in the example, the choices are labelled things like "Faculty or Staff", but the actual value is merely "s4" (and this is all that Director sees). Matches are exact, and are case-sensitive.

The Control File

In addition to the form, you must also create a control file. This is a plain text file, one destination per line. The first thing on the line must be the URL. Following this is a list of values to match against, separated by spaces. (Multiple spaces are the same as a single space.)

Comments are supported, but blank lines are not. To create a comment line, make sure the first character is a pound sign (hash mark, "#"). The rest of the line will be ignored.

When matching values, order is important. If more than one line in the control file matches the values returned by the form, only the first will be used (you can only go to one URL at a time, after all). The asterisk ("*") can be used as a wildcard value: it will match any value for that field. If fewer values are specified on a line in the control file than are returned by the form, all remaining values are treated as if they had been specified as asterisks. Therefore, a line with only a URL and no values acts as a default to be taken in the case no match is found (this should be the last line in the control file). The example above does not include such a default, and so unspecified combinations of values will result in an error message (try submitting the form with both values still set on "Select...").

Another example may serve to make this clearer. Assume the form has two fields, one of which can take on values a1, a2, a3, a4, and so on, up to a5, and the other of which similarly ranges from b1 to b5. Also assume a control file that consists of the following lines:

/~user/first-url   a3  b5
/~user/second-url  a1  b1
/~user/third-url   a1  *
/~user/fourth-url  *   b5
/~user/fifth-url   a2  b3
/~user/sixth-url   *   b3
/~user/seventh-url a2  
/~user/eighth-url   

Then if the form returns a1 and b1, the second URL is chosen, because it is an exact match. If the form returns a1 and b2, the third URL is chosen, because a1 is an exact match and the second value is specified as *, which matches anything. If the form returns a1 and b5, this matches both the third and the fourth URLs, but the third has priority (it comes before the other one in the file), and thus the third URL is the one chosen. The complete set of possible outcomes is as follows (using numbers to represent the chosen URL):

Notice that trailing asterisks are unnecessary, but allowed; the fourth line in the example above specifies an asterisk, while the seventh does not. They both work in exactly the same way. The eighth line acts as a default, and catches any combinations not explicitly catered to in other lines.

Limitations

There are not many limitations. The form can contain any number of fields, and each field can have any number of choices. There are no explicit limitations on the number of lines in a control file, and the lines can be up to 4K long each. There are no specific limits on the sizes of the value strings in either the form or the control file, but it would probably be more convenient for the author if they were kept reasonably short.

One "limitation" of sorts that is probably worth mentioning is that destination pages reached via the Director CGI cannot be bookmarked. The browser does not show the actual URL of the destination page, but instead shows the URL in the ACTION attribute of the form. Because bookmarking does not retain the form data, the bookmark doesn't work (Director gives an error message to let you know this, if you try to go to a bookmarked entry).

Troubleshooting

Note: This CGI program must only be used as part of a form. Simple links, such as the following, do not work:

Invoking the CGI by directly entering a URL will not work either. Likewise, using a "mailto" form or using METHOD="GET" with a form will fail. The CGI will produce an error message, so you should be able to detect problems immediately, if you test your page as soon as you put it up.