Documentation for the Mail Form CGI scripts.
Created by James Pattie, March 13-14, 2000.
Copyright (c) 2000 PC & Web Xperience, Inc. http://www.pcxperience.com/


Files involved:
	ParseMailForms.pm - The configuration parser and HTML generator.
	mailform.cgi	  - The CGI script that displays the form and e-mails the results.
	form.conf	  - The form configuration file.  Could be called something else if desired.
	.htaccess         - Apache control file that prevents people from seeing the files in the mailform directory.
  HTMLObject (Base, CGILib) - Used to actually generate the overall HTML file and to parse in the form data.


Configuration options:
	ParseMailForms.pm - Nothing is user configurable.
	mailform.cgi	  - Configuration file location, Sendmail location and options,
			    Color to display the * in for errors, Company name to
			    display on success and their URL. (These are now configurable on a per form basis)
			    The script now defaults to /var/www/html for the document root and uses the value
			    that the server gives (when run under a web server).  The script also checks to make
			    sure it can load the required modules and fails gracefully instead of just letting
			    the program bomb.  This is mainly for systems where the user can't get to the log files.
	form.conf	  - The rest of this document will cover the layout and format of the file.  This now can
			    be named something else as long as you specify it with the configFile parameter to
			    the mailform.cgi program.


File Locations:
The files ParseMailForms.pm, form.conf, HTMLObject/* and .htaccess must be in the directory mailform off the root
web directory.  In a normal Linux install this will be /home/httpd/html/mailform (RH 6.x) or /var/www/html/mailform
(RH 7.x).  mailform.cgi will default to this location and use the server specified location to look for the
configuration and parser files.  mailform.cgi should go in the cgi-bin directory of the website.

HTML usage:
Create a form in your html page that points to the mailform.cgi script and has a hidden value of form_name where the
value = the name of the form you want it to display.  The form must be defined in form.conf otherwise an error will
be displayed.
If you would like to specify an alternate config file to work with, use configFile=filename in your form or url.

  Ex.  <form method=post action="/cgi-bin/mailform.cgi">
         <input type=hidden name="form_name" value="form">
         <input type=hidden name="configFile" value="test.conf">
         <input type=submit value="Take our form for a spin" name="submit">
       </form>


form.conf - File Layout and valid commands (tags)

This file describes potentially multiple forms that the user would like to display and allow
guests to their site to fill in and have the results e-mailed to them upon filling in everything
that is required.

Comments may be made in the configuration file by starting a line with a # sign.  Any leading
white space or empty lines will be ignored while parsing the configuration file.

NOTE:  As of version 1.11 all config items of name=value format must have the value double quoted.  Ex. name="value"

A form is defined by having an opening <FORM NAME="name"> tag,
	a <MAILTO>, <MAILFROM>, <TITLE> and at least one <TEXT> and/or <CHECKBOX> tags,
	and the closing </FORM> tag.

For a form to be successfully submitted via e-mail the user has to submit at least one value,
so if all you are doing is using checkboxes, the user may be constantly presented with the
form if they either do not select any checkboxes (and all default to unchecked) or they have
cleared them all.  The script sees this as a new use of the form and so regenerates it instead
of submitting the form with the values that you expect (since a checkbox that is unchecked does
not send anything to the server).

Here is a list of all valid tags.  A * marks optional tags and/or items in a tag.
  Tags and tag items can be entered in lowercase but all other punctuation must be exactly as specified.
  There can be space at the front of the line, but no space once a tag or tag item is started unless it
  is part of the punctuation.  Ex. <FORM NAME = "name"> is now valid though < FORM NAME="name"> is not.
  The parser doesn't go out of it's way to try to help you figure this out, it just tells you it
  encountered an unknown Tag.  You can have white space around = in your tags, but that is it.


<FORM NAME="name">	name can be anything that is not already used for another FORM.
</FORM>

<DISABLE_HTML_MAIL> *		Makes the default Mail delivery route be through sendmail.  File Uploads are disabled and the e-mail is not using HTML.
<DISABLE_FILE_UPLOADS> * 	Replaces any file upload tags with the mailto link even if using HTML mail.

<MAIL_SERVER>IP Address or hostname</MAIL_SERVER> *	The Host that we send mail to, if not using sendmail.  Defaults to 127.0.0.1 if not specified.  If hostname used must end in com or net or edu or org.

<MAILTO>
  DISPLAYAS="name"		Real Name to display as. (ex.: John Doe)
  ADDRESS="e-mail address"	E-mail address to send to must be in .com, .net, .org, or .edu
</MAILTO>

<MAILFROM>
  DISPLAYAS="name"		Same as <MAILTO>
  ADDRESS="e-mail address"
</MAILFROM>

<TITLE>title text</TITLE>	Defines the TITLE of the HTML document.

<BACKGROUND_IMAGE>image name</BACKGROUND_IMAGE> *	Defines a background image to display.  Defaults to not being used.  If used, sets this image as the background for the BODY and the TABLE.

<TEXT>
  NAME="variable name"		The name of the form item. (must be unique)
  LABEL="string to display"	The string to display that describes the item.
  LABEL_LOCATION="left|right" *	Label on the left or right of the item. Default = left
  DEFAULT_VALUE="string" *	The default value to display. Default = ""
  MAXLENGTH="number"	*	The maximum number of characters to accept. Must be > 0.
  SIZE="number" *			The size of the display box to show. Must be > 0.
  REQUIRED="true|false" *		Is this text box required?  Default = false
  VALIDITY_MASK="Regular expression" *	The regular expression to check with to make sure the user entered a valid value. Default = ".+"
  CASE_SENSITIVE="true|false" *	Should the regular expression check be case sensitive or not? (mainly for custom cases). Default = false
  ALIGN="left|right|center" *	Align the item in the table as specified.  Default = left
  NOTE="string"	*		User customizable note to display to the user describing what is requested.
  NOTE_ALIGN="top|bottom" *	The location of the Note, either on top or below the text field. (If TEXT align = center, will always be in the cell with the edit field.) Defaults to bottom.
  NOTE_COLOR="color" *		The custom color to display the note in.  Defaults to the Current foreground color of the cell if not specified.
  TYPE="text|password|textarea"*  The type of the TEXT tag to display.  Default is text.
  ROWS="number" *			The number of rows to display in the text area.  Not valid with text or password (will silently disregard). Default = 5.  Must be > 0.
  COLUMNS="number" *		The number of columns to display in the text area. Not valid with text or password (will silently disregard).  Default = 80.  Must be > 0.
  TEXT_WRAP="off|virtual|physical" *	The style of word wrapping. Off doesn't wrap, virtual wraps but sends as long line until you hit Enter, physical sends exactly as you type it.  Default = virtual.
</TEXT>

<CHECKBOX>
  NAME="variable name"		The name of the form item.  (must be unique)
  LABEL="string to display"	The string to display that describes the item.
  LABEL_LOCATION="left|right" *	Label on the left or right of the item.  Default = left
  DEFAULT_VALUE="on|off"	*	If on, then the checkbox will be CHECKED.  Default = off
  ALIGN="left|right|center" *	Align the item in the table as specified.  Default = left
</CHECKBOX>

<LABEL> *			Gets processed in the same order as encountered (same as TEXT and CHECKBOX) but just displays the string.
  TEXT="string"
  ALIGN="left|right|center" *	Default = left
</LABEL>

<FILE_UPLOAD> *			Allows the user to specify a file to upload and be attached to the form data e-mail.
  NAME="variable name"		The name of the form item. (must be unique)
  LABEL="string to display"	The string to display that describes the item.
  LABEL_LOCATION="left|right" *	Label on the left or right of the item. Default = left
  ALIGN="left|right|center" *	Align the item in the table as specified.  Default = left
  REQUIRED="true|false" *		Is this file upload required?  Default = false
  NOTE="string"	*		User customizable note to display to the user describing what is requested.
  NOTE_ALIGN="top|bottom" *	The location of the Note, either on top or below the file upload field. (If FILE_UPLOAD align = center, will always be in the cell with the file upload field.) Defaults to bottom.
  NOTE_COLOR="color" *		The custom color to display the note in.  Defaults to the Current foreground color of the cell if not specified.
</FILE_UPLOAD>

<RADIOBUTTON>
  NAME="variable name"		The name of the radio button.  (must be unique)
  LABEL="labels to display"	The string of label names to display, | seperated.  Must have the same amount as VALUE items.
  VALUE="values to return"	The string of values to return, | seperated.  Each value is matched up with the corresponding label.
  LABEL_LOCATION="left|right" *   Label on the left or right of the items. Default = left.  This applies to all items being created for this radio button sequence.
  ALIGN="left|right|center" *	Align the item in the table as specified.  Default = left.  This applies to all items being created for this radio button sequence.
  DEFAULT_INDEX="index" *		The index into the number of items (starting at 0) which should be selected.  If not specified, then the first item is marked as selected.
  NOTE="string"	*		User customizable note to display to the user describing what is requested.
  NOTE_ALIGN="top|bottom" *	The location of the Note, either on top or below the field.  Defaults to bottom.
  NOTE_COLOR="color" *		The custom color to display the note in.  Defaults to the Current foreground color of the cell if not specified.
</RADIOBUTTON>

<SELECT>
  NAME="variable name"		The name of the Select box.  (must be unique)
  LABEL="string to display"	The string to display that describes the item.
  LABEL_LOCATION="left|right" *	Label on the left or right of the item.  Default = left
  ITEMS="string"		The string of items, | seperated, that are to be displayed in the select box.
  VALUES="string" *		The string of values, | seperated, that are to be matched up with the items.  If not specified, then the items are used for the values. (Standard HTML design).
  DEFAULT_INDEX="index"	*	The index into the number of items (starting at 0) which should be selected.  If not specified, then the first item is selected.  Currently only 1 item can be defaultly selected even in a multi-select box.
  ALIGN="left|right|center" *	Align the item in the table as specified.  Default = left
  MULTISELECT="true|false" *	Denotes if this should be a multi-select list box.  Default = false.
  SIZE="number of rows to show" * Specifies how many rows should be shown.  Default = 0, which signals that we are not making it a box, but a drop down.
  WIDTH="number of pixels wide" * Specifies how wide the box should be.  Only valid if SIZE > 0.  Defaults to 150.  Minimum width I will support = 50.
</SELECT>

<CONFIRMATION_EMAIL>
  MODE="always|never|prompt"      Defaults to never
  ALIGN="left|right|center" *	If mode = prompt, then you can use these options to align the prompt text and checkbox.  Default = left
  LABEL="Receive a confirmation e-mail"
  LABEL_LOCATION="left|right" *   Label on the left or right of the item.  Default = left
  NAME="mailConfirm"		If mode = always, then a hidden attribute is set that has mailConfirm=Yes, else we use a
  				checkbox if mode = prompt.  This attribute can not be set by the form and no other
  				form item can have the variable name of mailConfirm.  This is just here for documentation.
</CONFIRMATION_EMAIL>

<SIMPLE_EMAIL>		        If present then we treat this form as a simple e-mail form, else we treat it normally.

<HEADER> *
  TEXT="html text"		The HTML text to display as the custom header.
</HEADER>

<FOOTER> *
  TEXT="html text"		The HTML text to display as the custom footer.
</FOOTER>

<TABLE_BACK>color</TABLE_BACK> *	Overrides this table row and any following to use this color for the background.  A color of 'reset' resets to the default color of the table.

<TEXT_FORE>color</TEXT_FORE> *		Overrides this table row and any following to use this color for the text foreground.  A color of 'reset' resets to the default text color.

<DEFAULT_TEXT_FORE>color</DEFAULT_TEXT_FORE> *	Sets the default Text foreground color for the document.  If not set, Default = black

<DEFAULT_TEXT_BACK>color</DEFAULT_TEXT_BACK> *	Sets the default Text background color for the document.  If not set, Default = white

<TABLE> *
  CELLPADDING="number" *		value must be >= 0  If not set, Default = 2
  CELLSPACING="number" *		value must be >= 0  If not set, Default = 0
  BORDER="number"			value must be >= 0 (0 = no border)  If not set, Default = 0
  WIDTH="number%|number"		specifies the width of the table in a percentage or actual number of pixels.  If not set, Default = 100%
  ALIGN="left|right"		Overrides the default of CENTER to align left or right.
  BACK_COLOR="color"		Specifies the default background color of the table.  If not set, Default = Default Text Back or User Specified Back color.
</TABLE>

<DISPLAY_MAIL_TO> *		Turns on displaying the mailto line that says who the data is going to.

<HIDE_CREDIT> *			Turns off displaying the PC Xperience, Inc. created by line.

<COMPANY_NAME>name</COMPANY_NAME> *	Defines the Company name to display on the Success page.  If not set, Default = "PC Xperience, Inc."

<COMPANY_URL>url</COMPANY_URL>	*	Defines the Company url to display on the Success page.  If not set, Default = "http://www.pcxperience.com/"

<THANK_YOU>message</THANK_YOU>	*	Defines the Thank You message to display on the Success page.  If not set, Default = "Thank you for your interest."

<ERROR_COLOR>color</ERROR_COLOR> *	Defines the Color to display the Error Item marker in for errors.  If not set, Default = red.

<ERROR_ITEM>string</ERROR_ITEM> *	Defines the Error Item marker.  If not set, Default = "*"

<REQUIRED_ITEM_COLOR>color</REQUIRED_ITEM_COLOR> *	Defines the Color to display the Required Item marker.  If not set, Default = blue.

<REQUIRED_ITEM>string</REQUIRED_ITEM> *	Defines the Required Item marker.  If not set, Default = "(+)"

<LINK_COLOR>color</LINK_COLOR> *	Defines the default color of the Links.  If not set, Defaults to Blue.

<LINK_VISITED>color</LINK_VISITED> *	Defines the default color of the links that have been visited.  If not set, Defaults to Blue.

<LINK_ACTIVE>color</LINK_ACTIVE> *	Defines the default color of the link when the mouse hovers over it.  If not set, Defaults to Blue.

<LINK_HOVER>color</LINK_HOVER> * 	Defines the default color of the link when the user clicks it.  If not set, Defaults to Red.

<LINK_DECORATION>on|off</LINK_DECORATION> * Defines if the links should be underlined.  If not set, Defaults to off.

<RETURNTO_URL>url</RETURNTO_URL> *	Defines the url address to display as a return to link.  If not set, Default = "http://www.pcxperience.com/".

NOTE:  In <TABLE>, <TEXT> and <CHECKBOX> tag items can be specified multiple times.  The last instance will be the value ultimately used (if valid).