Return CGI Library
Return Form Handling

OK... hopefully you've seen example 2 where we demonstrated how to use a template to format an e-mail message.

This time we're going to drop the e-mail message and just worry about keeping the screen that the browser gets after submitting the form looking more appropriate than the default "Thank You" screen.

There are two very different methods for controlling the "results screen":

1. You can simply send the browser off to a page you've written :-).
2. Or, you can take the form contents and format them using a template.

Let's cover them in order.

Directing the browser to a specific page

Sending the browser to a page of your choice is simple: define a field called REDIRECT and put an absolute URL in it. By "absolute" we mean a link that starts either with "/" or with "http://host/". The reason is simple: the browser thinks it's in the /cgi-bin directory so if you don't specify the full path to the page, it will try to get it from the /cgi-bin directory... check your error log, this stands out like a sore thumb.

oops!, upon reviewing this page, it seems that the example using a <select> to pick a URL to jump to is much more complex than the normal usage, thus a simpler example is called for.

HTML for the basic example:

<form action="/cgi-bin/mail2" method='post">
<input type="hidden" name="REDIRECT" value="/gadgets/mail2/" />
<input type="submit" value="click here to go to the mail2 index" />
</form>

Form for the basic example:

Step by step description of the preceding example

Lines 1 defines the start of the form and tells it to use the /cgi-bin/mail2 gadget. It also specifies the post method, but this isn't required.

Line2 defines a hidden variable called REDIRECT. This variable contains a page on this server to jump to. Note that the path is specified from the webserver's "/" directory.

Line 3 is a submit button with a long label.

Line 4 ends the form.

A more sophisticated example

You can even make the REDIRECT field a select field if you just want to generate a list of links. (We've heard that not all browsers treat the value clause in a select list correctly, so this might not be the best of ideas.)

Time for the example :-).

<form action="/cgi-bin/mail2" method="post">
Where do you want to jump to? <select name="REDIRECT">
<option value="/gadgets/">
  /gadgets page - The index of gadgets </option>
<option value="/gadgets/mail2/" selected="selected">
  /gadgets/mail2 page - The /cgi-bin/mail2 page </option>
<option value="/gadgets/mail2/page3.html">
  back to this page </option>
<option value="/">
  Top of the server </option>
</select>
<input type="submit" value="Go There" />
</form>

And the real form:

OK, that's about all there is to using the REDIRECT capability of the gadget.

P.S. If your browser doesn't work with the links above, please send a message to support@baremetal.com and tell us which browser you are using!

Formatting the form contents and sending those back to the browser

This is a fairly simple operation. You need to define an HTML template to drop the form contents into. We're going to be lazy and use pretty much the same form as above, but this time it will be a two step jump. (This is a fun one, you get to see the CGI generated HTML.)

Here's the template:

Here is the link to the page you requested:


<a href="{URL}">{URL}<A>

Here's the link to our template: page3.tpl . Note that the URL to the file ends in page3.tpl ... that's the value we need to specify as the name of the template.

Here's the HTML for the form:

<form action="/cgi-bin/mail2" method="post">
<input type="hidden" name="REPLY" value="page3.tpl" />
Where do you want to jump to? <select name="URL">
<option value="/gadgets/">
  /gadgets page - The index of gadgets </option>
<option value="/gadgets/mail2/" selected="selected">
  /gadgets/mail2 page - The /cgi-bin/mail2 page </option>
<option value="/gadgets/mail2/page3.html">
  back to this page </option>
<option value="/">
  Top of the server</option>
</select>
<input type="submit" value="Go There" />
</form>

And here's the real form:

Note that the same caveats about crippled browsers not handling the value= parameter of a <select> tag applies here for the same reasons.

Summary

• A form value of REDIRECT specifies a URL to send the browser to after submitting a form.
  
  
• A form value of REPLY specifies the path to a template to be used to send a formatted page back to the browser.
  
  
• REDIRECT and REPLY are incompatible. You can't do both at once :-(
  
  
• REDIRECT and REPLY are compatible with the E-mail options and the save options.