TFmail KDS Internet TFmail

NAME

TFmail - generic HTML form to e-mail gateway

SYNOPSIS

<form action="/cgi-bin/TFmail.pl" method="post" ...>

DESCRIPTION

TFmail is a script which allows you to receive the results of an HTML form submission via an email message.

TFmail is *not* a plug-in replacement for FormMail.pl, although it has a lot of the same features. TFmail is configured via text files on the server rather than hidden form fields, has templates for output, and can support HTTP file uploads.

FILES

TFmail uses the following files:

default.trc
The main configuration file

spage.trt
The template file that controls the layout of the success page

missing.trt
The template file that controls the layout of the page presented to the user if some required fields have been left blank

email.trt
The template file that controls the layout of the email body

OUTPUT CUSTOMIZATION

The .trt files are templates used by TFmail to generate the output HTML and the body of the email. You can edit them to change the look of the output before uploading them to the CONFIG_ROOT directory.

The character combinations "{=" and "=}" are used to mark template directives. Whenever TFmail encounters a template directive, it replaces it with a value. For example, the template directive {= date =} will be replaced with the current date. There are also directives for introducing environment variables and CGI form input values, and a few others.

For example, by default TFmail will use the template email.trt to generate the body of the email. By default that template looks like this:

%% NMS email template file %% Below is the result of your feedback form. It was submitted {= by_submitter =}on {= date =}. ---------------------------------------------------------------------- {= FOREACH input_field =} {= name =}: {= value =} {= END =} ----------------------------------------------------------------------

The first line just tells TFmail that this is indeed a template file for an email body - it won't be included in the output.

The {= by_submitter =} directive generates the user's email address and real name followed the the string "by ", if there are email address and realname inputs in the form. If TFmail can't work out the user's email address then the {= by_submitter =} directive produces nothing. The "by " string was made part of the directive output so that the sentence would make sense in either case. The word 'by' can be replaced by setting the "by_submitter_by" configuration directive to the required text.

The {= FOREACH input_field =} directive repeats the lines between the FOREACH line and the END line for each field in the form who's name starts with a letter or a number.

If everything goes OK and the email is sent, TFmail presents a success page to the user. By default, that success page comes from the spage.trt template file, which defaults to this:

%% NMS html template file %% <?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Thank You</title> <link rel="stylesheet" type="text/css" href="/css/nms.css" /> <style> h1.title { text-align : center; } </style> </head> <body> <h1 class="title">Thank You</h1> <p>Below is what you submitted on {= date =}</p> <hr size="1" width="75%" /> {= FOREACH input_field =} <p><b>{= name =}:</b> {= value =}</p> {= END =} <hr size="1" width="75%" /> <p align="center"> <font size="-1"> <a href="http://nms-cgi.sourceforge.net/">TFmail</a> © 2002 London Perl Mongers </font> </p> </body> </html>

You can change these templates to anything you like, giving you full control over the look of the output. You don't have to include the {= FOREACH input_field =} directive or the {= date =} directive unless you want to.

You can use "param" directives to get at the values of individual CGI parameters. The directive {= param.foo =} will output the value of the "foo" CGI parameter, if there is one.

For example, if your HTML form has only two inputs, "name" and "age", then your success page template file might look like this:

%% NMS html template file %% <?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Thank You</title> </head> <body> <h1>Thank You {= param.name =}</h1> <p> Thanks {= param.name =} for registering your age as <b>{= param.age =}</b>. Your results have been added to our database. </p> </body> </html>

In a similar way, you can access the CGI environment variables via "env" template directives. For example:

%% NMS html template file %% <?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Thank You</title> </head> <body> <h1>Thank You {= param.name =}</h1> <p> Thanks {= param.name =} for registering your age as <b>{= param.age =}</b>. Your results have been added to our database. </p> <p> Note: we have logged your IP address as {= env.REMOTE_ADDR =}, and we will be reporting you to the FBI if you lied about your age. Have a nice day. </p. </body> </html>

You can also use these "param" and "env" template directives in the email template, to get finer control over the body of the email.

CONFIGURATION FILES

TFmail reads its configuration from a configuration file. By default, that file is default.trc in whatever directory you set for CONFIG_ROOT above.

If you have several forms on your site using TFmail, each will need its own configuration file. You can control TFmail's choice of configuration file via the "_config" hidden form field. For example, if you added the line:

to one of your HTML forms, then TFmail would use foo.trc in the CONFIG_ROOT directory as its configuration file when processing that form.

The choice of configuration file is the only thing that can be configured via a hidden form field.

The first line of the configuration file has to be exactly the text:

%% NMS configuration file %%

Lines starting with '#' are ignored, and configuration values are set by putting the name of the configuration setting at the start of a line, followed by a ':' character, followed by the value for that setting. The value can be split over several lines.

One configuration value that you must set is "recipient", the email address to which the form results should be mailed. For example, your configuration file might look like:

%% NMS configuration file %% # # This is my configuration file # recipient: me@my.domain

You can have several recipients set, in which case the form results will be copied to all of them:

%% NMS configuration file %% # # This is my configuration file # recipient: me@my.domain, some-else@my.domain

Other things that can be set in the configuration file are:

email_template
The template file to use for the body of the email. Default: email

success_page_template
The template file to use for the main HTML success page, displayed when the email has been sent. Default: spage

sort
This sets the order in which the {= FOREACH input_field =} directive processes the CGI parameters. It can be the string 'alphabetic' for alphabetic order, or the string "order:" followed by a comma separated list of the parameter names. Default: the parameters are output in the order in which they occur in the HTTP request.

print_blank_fields
If this is set to a true value then fields that the user left blank will be visited by the {= FOREACH input_field =} directive. Normally, blank fields are suppressed to save space. Default: 0

subject
The subject for the email. Default: "WWW Form Submission".

email_input
The name of the CGI parameter that will hold the user's email address. Used by TFmail to set the From field of the email. Default: no email_input, the mail comes from POSTMASTER.

realname_input
The name of the CGI parameter that will hold the user's full name. Used by TFmail to set the comment part of the From field of the email if a valid email address was found in the email_input input. Default: none, so there will be no comment on the From address.

by_submitter_by
The phrase added by the {= by_submitter =} template directive when outputting the user's email address. Default: 'by'.

redirect
If this configuration value is set, then it must be a URL and TFmail will generate a redirect to that URL on success, instead of using the success page template.

required
A list of the names of inputs that the user cannot leave blank. If any of these are blank, then the submission will not be accepted. Default: no fields are required.

missing_template
The HTML template file used to generate the page that the user sees if they leave a required field blank.

missing_fields_redirect
If this configuration value is set then it must be a URL and TFmail will generate a redirect to that URL instead of using a template if the user leaves a required field blank.

confirmation_template
If this field is set then it must be the name of an email template that will be used to send a mail back to the user confirming their submission. CAUTION: since the user could give any email address (not just their own) and submit repeatedly, there is a risk that some nasty person will use this to mailbomb a third party. Only switch this on if you really need it. Template directives that depend on user input will be disabled for this template, so that this feature can't be used to send SPAM. Default: no confirmation email.

confirmation_subject
The subject for the confirmation email, if it is activated by the confirmation_template directive above.

logfile
The name of a file to which data will be appended for each successful run of the script. The name is relative to the LOGFILE_ROOT directory and does not include the LOGFILE_EXT file extension. Default: no logging. Note that logging is disabled unless the LOGFILE_ROOT constant in the script is set.

log_template
The template file used to construct the text that gets appended to the log file if the logfile setting above is set. Default: log

modify_html_files
A list of the names of one or more HTML files into which TFmail should insert text, relative to the HTMLFILE_ROOT directory and without the HTMLFILE_EXT file extension. See the section below on inserting text into HTML files.

no_email
Set this to a true value to prevent the main e-mail from being sent. You might wish to do that if you're using TFmail to record data to a log file and don't need it mailed as well.

INLINE TEMPLATES

If you don't want to have a separate file for each template, you can choose to put some or all of the templates directly into the configuration file instead, putting a '%' character at the start of each line.

For example, rather than having the configuration file line:

email_template: my_email_template

... and a separate my_email_template.trt file with the text:

%% NMS email template file %% This is the email. remote address: {= env.REMOTE_ADDR =} user agent: {= env.HTTP_USER_AGENT =} referer: {= env.HTTP_REFERER =} The name they entered was: {= param.name =}

... you could just have the block:

email_template: %This is the email. % %remote address: {= env.REMOTE_ADDR =} %user agent: {= env.HTTP_USER_AGENT =} %referer: {= env.HTTP_REFERER =} % %The name they entered was: {= param.name =}

... in the configuration file. You can do this for any of the configuration variables listed above that expect a template file as a value.

Note that you must leave out the %% NMS ???? template file %% line when using an inline template like this.

FILE UPLOADS

File uploads are disabled.

INSERTING TEXT INTO HTML FILES

As well as sending email and writing log files, TFmail can be made to insert some text into the middle of an existing HTML file. The HTMLFILE_ROOT constant in the script should be set to the filesystem path under which all of the HTML files that you might want TFmail to modify reside.

For example, to use TFmail as a guestbook script, with your guestbook stored in the file /www/sites/31337/guestbook.html, you might set the HTMLFILE_ROOT constant to '/www/sites/31337' and put the following in a guestbook.trc file:

%% NMS configuration file %% no_email: 1 modify_html_files: guestbook htmlfile_template_guestbook: % <p><b>Date:</b>{= date =}</p> % <p><b>Name:</b>{= param.name =}</p> % <p><b>Comments:</b>{= param.comments =}</p> % <hr /> required: name,comments missing_template: %<?xml version="1.0" encoding="iso-8859-1"?> %<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" % "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> %<html> % <head> % <title>Missing Fields</title> % <link rel="stylesheet" type="text/css" href="/css/nms.css" /> % </head> % <body> % <p> % You must fill in both the <b>name</b> and <b>comments</b> fields. % Please try again. % </p> % <form method="post"> % <input type="hidden" name="_config" value="guestbook" /> % <p>Your Name: <input type="text" name="name" size="30" value="{= param.name =}" /></p> % <p> % Comments:<br /> % <textarea name="comments" cols="60" rows="4">{= param.comments =}</textarea> % </p> % <p><input type="submit" /> * <input type="reset" /></p> % </form> % <hr /> % </body> %</html> redirect: http://www.your.domain/thankyou.html

... and you might put something like this in the guestbook.html file:

<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Guestbook</title> <link rel="stylesheet" type="text/css" href="/css/nms.css" /> </head> <body> <h1>Guestbook</h1> <p>Thank you for visiting our pages. We would love it if you would <a href="addguest.html">Add</a> to this guestbook we are keeping!</p> <hr /> <!-- NMS insert below --> </body> </html>

... and addguest.html would probably look something like:

<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <title>Add to our Guestbook</title> <link rel="stylesheet" type="text/css" href="/css/nms.css" /> </head> <body> <h1>Add to our Guestbook</h1> <p>Fill in the blanks below to add to our guestbook.</p> <hr /> <form method="post" action="http://www.your.domain/cgi-bin/TFmail.pl"> <input type="hidden" name="_config" value="guestbook" /> <p>Your Name: <input type="text" name="name" size="30" /></p> <p>Comments:<br /><textarea name="comments" cols="60" rows="4"></textarea></p> <p><input type="submit" /> * <input type="reset" /></p> </form> <hr /> </body> </html>

DIAGNOSTICS


COPYRIGHT

TFMail Copyright © 2002 London Perl Mongers, All rights reserved. For more information visit "nms - Web Scripts Written by Experts" at http://nms-cgi.sourceforge.net/.

The file MIME_Lite.pm is copyright ZeeGee Software Inc, see the file for details.


TFmail KDS Internet TFmail