Zot-Dispatch 1.0 Documentation

NEW!!! Zot-Dispatch 2.0 is out and can be found at
http://www.oac.uci.edu/X/W6/zd/2.0/ZD-2.0-Doc.html

This document can be found at the URL: http://www.oac.uci.edu/X/W6/forms/zot-dispatch/ZD-Doc.html

Documents on the World Wide Web (WWW) are often written in HyperText Mark-up Language (HTML). HTML provides formatting information about a document to the client (viewer for the World Wide Web) used for viewing the document. HTML allows interactive elements to be placed into a document so that a user viewing it can enter information or make selections. Documents including these interactive elements are often called FORMS. FORMS need to have a program associated with them which can process the information that is entered by the user.

The information entered into a FORM is sent to an HTTP Server (HyperText Transfer Protocol) which then starts a CGI (Common Gateway Interface) program and feeds that information to it. CGI is the protocol with which a program can communicate with HTTP Servers. Because it is rare that any two FORMS would be exactly the same, it is often necessary to write or compile special programs to handle each form, and because CGI programs work with the HTTP server it is then necessary to have that program placed in a directory from which it can be executed by the server.

Zot-Dispatch (ZD) is a CGI compliant program written to alleviate the problems of writing or compiling special code to handle WWW FORMS. Zot-Dispatch can be told, via the HTML in the FORM itself, how to handle your specific FORM.

What can ZD do? It can perform the following Actions:

Reflect (echo) information to the user`s client.
E-mail information to multiple e-mail addresses.
Append information to multiple files.

For each of the Actions listed above, the information that Zot-Dispatch outputs can be of a specific format.

Zot-Dispatch can also:

Grab Environment Variables set by the HTTP server which contain useful information such as from which host the FORM was submitted.
Enter the date and time into a response.
Set the subject line of any email sent.
E-mail any errors that occur to a user specified in the FORM.

Before continuing it is best that you read and fully understand the documentation on writing HTML, and writing HTML FORMS. If you have read and understand these documents, what follows will make much more sense.

To set up Zot-Dispatch:

Retrieve the following two programs:

zd.pl
Zot-Dispatch source code in Perl
cgi-lib.pl
Library with necessary subroutines for Zot-Dispatch
Put both programs in the/a cgi-bin directory on your server.
Make sure both programs are readable and executable by the server.
Check the first few lines of each program to configure them for your server/machine.
- Check the path of Perl.
- Check the paths of date and mhmail
- Configure Address Chopping and Alias Files if desired.
- Choose your separator (for the ZD-Method fields).
- Set the $cgilib variable to the path of the directory that contains cgi-lib.pl

ZD-Comments: An application of Zot-Dispatch

ZD-Comments is nothing more than a few lines of HTML that can be added to your documents to get a button which, when pressed, returns to the user a comment form. The user can enter into this form their comments about the document they were just reading. When this form is submitted, an e-mail message is sent to the author of the original document stating the URL of the document that is being commented on, the title of the document, and the user's e-mail address, name, and message.

All that you need to do is include the following HTML in your document, and edit the values of the DOC-URL, DOC-ID, DOC-TITLE, and SEND-TO hidden variables.

The values of the four hidden variables should contain the following:

DOC-URL: This hidden variable should contain the URL of the document being commented on. This value should not (but can) be left empty.
DOC-ID: This hidden variable should contain any other information you may find useful in identifying the document, such as revision number, date of publication, etc. This value can be left empty.
DOC-TITLE: This hidden variable should contain the title of the document that is being commented on. This can be the same as the title you have in the <TITLE></TITLE> tags. This value should not (but can) be left empty.
SEND-TO: This hidden variable should contain the e-mail address to which the user's comments will be sent. This value cannot be left blank and should be a valid Internet address.

The form that is returned to the user has input fields for the user's name, e-mail address, and message, in addition to a button which allows the user to choose to receive a copy of the e-mail message as well. If the DOC-URL hidden variable is set correctly, then the form will also include a link back to the original document.

The HTML follows:

<FORM METHOD=POST ACTION="http://www.oac.uci.edu/cgi-bin/zd.cgi">
<INPUT TYPE=hidden NAME=DOC-URL 
        VALUE="">
<INPUT TYPE=hidden NAME=DOC-ID
        VALUE="">
<INPUT TYPE=hidden NAME=DOC-TITLE
        VALUE="">
<INPUT TYPE=hidden NAME=SEND-TO
        VALUE="">
<INPUT TYPE=hidden NAME=ZD-Method
        VALUE="ZD-Reflect;;file:/Web/doc/X/W6/zd/comment-form.template">
<INPUT TYPE=submit NAME=submit VALUE="Send Comments">
</FORM>

A few final notes:
The HTML above cannot be placed within another form. If so, ZD-Comments will not work.
If you would like to change the message that the button contains you need only change the value "Send Comments"
An example of ZD-Comments is below.

If you have any problems, comments or requests with/for Zot-Dispatch you can click the "Send us Feedback" button above, or e-mail them to Leonard Megliola (lmegliol@uci.edu).

LMIII
(Last Revised April 19, 1996)