Advanced cgiemail Usage

After becoming familiar with techniques described in the cgiemail user guide, you may want to attempt some more advanced techniques.

	Using cgifile
	Custom failure messages
	Templates for success/failure pages
	Special formatting
	Special variables

Using cgifile:

Your webmaster may have chosen to install a program called cgifile along with cgiemail and cgiecho. This program uses a template and ACTION like cgiemail, but appends information to a file rather than mailing it. Due to security considerations, there are certain restrictions on this file.

	It must be named `incoming.txt`.
	It must be in the same directory as the template file.
	It must exist already before cgifile is run.
	It must be writeable by the uid your web server runs under. Get help from your webmaster if you don't know how to set permissions to make this happen.

Note: End-of-line markers will be translated to Unix style, and any leading whitespace in the template will be removed. This program is not meant for uploading binary files.

Custom failure messages:

With release 1.4, cgiemail introduces a new hidden variable called failure. It works just like the success variable, but for failure rather than success. This variable should be used only after completely debugging a form.

Templates for success/failure pages:

In releases prior to 1.4, the success variable was required to start with / or with http://. Now a value like "mypage.html" will be interpreted as an HTML page template in the same directory as the mail template.

Special formatting:

To make a form value show up correctly on a success/failure template, a special formatting directive has been added. It translates certain characters (<, >, &, ") into their appropriate HTML character entities. It is used like this:

[%H,mailaddr]

To include form values in URLs, another special formatting directive has been added. Here is an example of its use:

<a href="/bin/cgicso?query=[%U,name]">lookup</a>

Special variables:

Although the date is always included in the header of a mail message, you may also include it in the body by putting [cgidate] in your template file.

Insert [cgirelease] where you want the release number (e.g. 1.4) inserted. Always use this in custom failure templates.

Insert [cgierrmsg] where you want the error message inserted. Always use this in custom failure templates.

Insert [cgierrinfo] where you want additional error information inserted. Always use this in custom failure templates.

Here is an example custom error template:

You didn't fill everything in!

Please go back and fill in at least the required information:

name

quest

Here is the exact error message:
[cgierrmsg]
[%H,cgierrinfo]
cgiemail [cgirelease]

Note that this page gives the user friendly information about what went wrong 99% of the time (a required field was left blank), but also includes error information in case something else goes wrong. Without this information, debugging could be painful.