#set TITLE = "working with html forms"
#include top

.SH Working with HTML forms
One of QUISP's main strengths is HTML forms
work.  This document assumes that you already know how to code 
#set FILE = "http://archive.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/fill-out-forms/overview.html"
#set TAG = "HTML forms."
#include link
Two QUISP pages must be set up to implement a form.  The first is the \fBform page\fR; it contains 
the form.  The second is called the \fBtarget page\fR; it is invoked when the 
user "submits" the form, and has all of the user responses available as variables.
The target page may build SQL statements to save submitted data.
Or, it may just issue a query based on the submitted parameters.  Sometimes with
the latter, the form and target pages are actually the same page, invoked cyclically.
.LP
A basic example using form \fC<INPUT>\fR fields is shown below. 
.LP
QUISP also provides additional support (documented separately) for:
.IP \(bu
#set FILE = "oplist.html"
#set TAG = "SELECT option lists (single and multi choice) using #optionlist"
#include link
.IP \(bu
#set FILE = "oplist.html"
#set TAG = "TEXTAREA fields using #showtext and #savetext"
#include link
.IP \(bu
#set FILE = "allresponses.html"
#set TAG = "Big lists of checkboxes (etc.) using #allresponses"
#include link

#include space
.SH Working examples
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index"
#set TAG = "Located here"
#include link
(also in your \fC./qexamples\fR directory).

#include space
.SH A basic form and target page
Suppose we have the following HTML form with several \fC<INPUT>\fR fields.
The form method is \fCGET\fR but \fCPOST\fR can also be used.
.nf
 \0 <form action="@@CGIPROG" method=GET>
 \0 #formtarget mytarget
 \0 Enter your first name: 
 \0 <input name=firstname value="" size=20 maxlen=20> <br>
 \0 Enter your last name: 
 \0 <input name=lastname value="" size=20 maxlen=20> <br>
 \0 <input type=submit>
 \0 </form>
.fi
The \fBtarget page\fR for the above form should be in a file in the \fC./pages\fR directory
named \fCmytarget\fR, and might look something like this:
.nf
 \0 #cgivar firstname, lastname
 \0 <h1>Hello, @@firstname @@lastname!!</h1>
.fi

.LP
A more elaborate 
#set FILE = "#de_example"
#set TAG = "data entry form example"
#include link
that includes database access is shown at the bottom of this page.  
Here are the descriptions for the basic HTML form QUISP directives:


#include space
.SH #formtarget
This directive should be used within the \fC<form>\fR construct.  It specifies the
name of the page that will be used to capture submitted responses and do something with
them, such as save them to a database.  The page name is relative to the \fC./pages\fR directory.
This directive works by generating a "hidden" form input field called \fBrtn\fR.
.br
Example: \fC#formtarget saver\fR

#include space
.SH #pass
May be used to pass variable(s) from the form page to the target page.
Useful when information is needed by the target page in addition to that provided by 
the submitted form fields.  
Note that variable names should not be specified with a leading at-sign (\fC@@\fR).
This directive works by generating "hidden" form input fields.
.br
Usage: \fC#pass  \fIvarname1\fR .. \fIvarnameN\fR
.br
Example: \fC#pass parm1, parm2\fR

.ig >>
<a name=de_example></a>
.>>
#include space

.SH A data entry form example
#set FILE = "http://quisp.sourceforge.net/cgi-bin/quisp?rtn=index#readwritedb"
#set TAG = "Located here"
#include link


#include bottom

