Yamform, which stands for "Yet Another Mail Form", is a forms-handling program for use with World Wide Web forms. The difference between yamform and other common mail-based forms-handling programs is that yamform allows the designer of the form to control the format of the resulting e-mailed report -- not just the input format but the output format as well.

Sections of this page:

• How to set up a form with yamform
• Proper use of yamform
• An example form
• For more information

• Make sure that you know how to create documents in HTML (HyperText Markup Language) and publish them on a WWW server. If you don't know how, contact the Consulting Center (x4983) or send e-mail to "riceinfo@rice.edu".

• Create an HTML document containing your form. This will call for the use of the <form> tag and one or more of the <input>, <select> and <textarea> tags. An introduction to HTML forms, including a number of examples, can be found in the NCSA Mosaic Fill-Out Form Support document.

• In the <action> attribute of the <form> tag, specify the URL of the yamform program, followed by a question mark and the e-mail address to which the form results are to be sent. Example:

  <form method=POST action="http://www.rice.edu/cgi-bin/yamform?cwis@rice.edu">
  

  Multiple e-mail addresses may be specified, separated by commas:

  <form method=POST action="http://www.rice.edu/cgi-bin/yamform?cwis@rice.edu,riddle@rice.edu">
  

• Within the boundaries of the <form> </form> tag, specify these special <input> tags:
  1. User's return e-mail address (name=from): an input field in which the user will specify his or her e-mail address. The header of the resulting e-mail will reflect the e-mail address entered by the user, and the user will receive a copy. It's helpful to prompt the user for a full e-mail address, not just a userid. Example:

     Enter your e-mail address: <input type=text name=from><br>
     <em>(Complete address, e.g. "jdoe@foo.edu"!)</em>
     

  2. Subject line (name=subject type=hidden): The subject line you wish to use for the resulting mail. Example:

     <input name=subject type=hidden value="Favorite color report from $from">
     

  3. Output format (name=outform type=hidden): The output format you wish to use for the resulting mail. It may contain embedded newlines. Example:

     <input name=outform type=hidden value="
                     Favorite color report
     
     Name:           $name
     E-mail address: $from
     Favorite color: $color
     ">
     

     Note that there is a limit of 1024 characters for the maximum length of a hidden field. In order to specify an output form longer than 1024 characters, you may break it into several hidden fields named outform1, outform2, outform3, etc. Example:

     <input name=outform1 type=hidden value="
                     Great Big Report
     
     Name:           $name
     E-mail address: $from
     Favorite color: $color
     ...
     ">
     <input name=outform2 type=hidden value="
     Favorite food:  $food
     Favorite drink: $drink
     ...
     ">
     

  Remember to reserve the field names from, subject and outform for these special fields.

  Note that both the subject line and the output format can contain the names of other input fields, each preceded by a dollar sign ($). The values input by the user will be substituted for the names of these fields before the mail is sent.

  If you use less than (<), greater than (>), ampersand (&), or quote (") characters within your hidden fields, you will have to escape them using ampersand entities in order not to confuse the HTML in your form. This is particularly important if you intend to produce HTML in your yamform output. For example, if your user entered a URL in the field $url and a title in the field $title, you could produce output containing the HTML for a link to the URL as follows:

  <input name=outform3 type=hidden value="
  &lt;a href=&quot;$url&quot;&gt;$title&lt;/a&gt;
  ">
  

• If you would like to summarize your yamform results in a spreadsheet, here's a trick to make it easy to extract results from your mailbox. Include in your output format a list of input fields laid out as comma-separated values, together with a unique keyword you can use to find the summary lines in your mailbox file. Any input fields which may include commas or spaces should be surrounded by quotation marks. For example:

  <input name=outform4 type=hidden value="
  FAVSUM,&quot;$name&quot;,$color,$food,$drink
  ">
  

  You can then use the Unix command grep to extract the summary lines from your mailbox file. The details will differ according to the system on which you receive your e-mail. If for example you are user "jroe" on the RUF, then you could extract the lines by logging into your RUF account and typing the following command at the Unix prompt:

  grep FAVSUM /var/mail/jroe
  

  The output from the grep command will be in a format suitable for importing into Excel or some other spreadsheet program.

Attention non-Rice users: Please refrain from setting up forms on non-Rice servers which post to the installation of yamform at Rice. If you wish, you may install the yamform source at your site, although please note that it is entirely unsupported by Rice.

• Widget request form
• Widget request form (HTML source)
• Resulting e-mail containing a widget request