ASForm encourages you to customize its operation, and writing your own templates for reports and Autoresponder messages is something that just begs to be done. One of the most frequently asked questions in HTML and CGI news groups is " How do I configure the formatting of my form processor's email messages?". For many of them, the answer is "You don't". Personally, I think that sucks ;-)
For some applications, a raw data dump might be all you need, and you can still have that if you want it. But, with ASForm you aren't stuck with it, and you never have to even see it.
Whether you use form data to fill in your messages or not, ASForm parses the messages looking for tags to replace with data. In this regard, it behaves a lot like an HTTP ("web") server with Server Side Includes always enabled. ASForm would be parsing the document(s) anyway looking for other things, so it might as well look for places to include data as long as it's there.
It's actually an easy process. You just write the message, whether it's an Autoresponder reply or a report, and use HTML-like tags that ASForm can find and replace with the proper values from your form's data.
Let's suppose for a moment that we have a form that is used simply as a mail interface so users don't have to use their own mail clients. In this form, we have only three fields, with the form put together this way:
<form action="/cgi-bin/asform.cgi" method="POST">
<p>Name: <input type="text" name="name" size=40 maxlength=80>
<p>Email: <input type="text" name="email" size=40 maxlength=80>
<p>Message: <input type="textarea" name="message" rows=50 columns=80>
<input type="submit" value="Send">
We have configured ASForm to look for a template for the Autoresponder named reply.txt. Here is our reply.txt file, with notes in underlined italics that would not appear in a real reply template:
asformreply: (Must have this, or ASForm won't use this file)
From: "My Company" <firstname.lastname@example.org> Note the syntax!
Subject: Thanks for contacting My Company
Thank you for visiting My Company on the web <time>
We appreciate that you took time from your busy day
to contact us, and we will get back to you as soon as
Confirming your message to us, you wrote:
My Company Sales
It's just that simple. You probably noticed that the field time didn't appear in our form -- because it's so often useful, ASForm makes it available to you wherever you need it. The first three lines in our above example will not appear in the body of the message. asformreply: (and anything that appears on the line with it) will be discarded, and the From: and Subject: lines will be used to create the mail header, overriding whatever may be in your configuration file. Any blank lines between them will carry through to the body of the message. Any tags you use that are null (undefined) in the form data will be filled with (undefined), so you'll probably want to require those fields that you intend to use in templates.
Please note that in Autoresponder messages, you can't alter the header fields From: or Subject: based upon user input and the tags that can be applied to the message body.
If you intend to use of this feature, you'll probably want to make sure that your field values are something suitable for inclusion in what is otherwise a nice looking email message.
ASForm provided variables
Some things are just so handy that ASForm provides them for you without your having to do anything extraordinary to get them:
- <time> gives you the date and time (AKA "time string") in the format you've specified in your configuration file, if you have, or GMT by default. In this beta release, it will look something like:
Fri Feb 12 19:58:27 1999 GMT
- <referer> gives you the URL of the page the form was on that invoked ASForm, if it was set by the browser, or (undefined) if not.
- <host> provides either the remote host name (the name of the user's machine) or, more commonly, it's IP address. You get the remote host name only if it's available from the transaction information, and don't get a choice. Sorry.
- <autoreply> (form reports only) provides a sentence indicating whether or not the user (or at least the HTML form) caused an Autoresponder message to be attempted if you are running the Autoresponder in user mode. For example:
The user did not request a confirmation from the Autoresponder.
- <ar_result> (form reports only) indicates with a sentence whether or not the Autoresponder succeeded in passing the Autoresponder message to the SMTP server. Example:
Autoresponder succeeded in mailing to user.
- <dump> (form reports only) provides the raw data dump, similar to echo but with all fields exposed, in a single column.
If you enabled echo (by setting its argument to on) in your configuration file, a raw data dump would appear at the bottom of this message, starting on the third line below your last line. If you have some data that you don't want echoed, name those fields with something that begins with hide_ to keep them out of the echo.
Also note that if you have moved HTTP environment variables into your sort order, they will then become visible to the echo -- if you don't want them to appear in your echo, and you can use Server Side Includes, you can use the workaround explained in "Writing Forms for Use with ASForm".
If you want to include an environment variable that you have ASForm configured to capture in an Autoresponder message or a form report, it works just like including form data. For example: <HTTP_REFERER> in your template will drop the URL of the page from which ASForm was invoked into the message ASForm sends. (If this is the one you're after, though, you might find it easier to just use <referer> which is provided for your convenience.)
ASForm automagically strips the fields config and autorespond from the echo, and suppresses null (undefined) fields in it, as well. Those HTTP environment variables that you haven't added to your sort order will not be echoed, either. (Some paranoid people don't want to know about the footprints they leave as they travel the internet. Who could blame them?)
Differences that apply to reports
Instead of asformreply: you have to use asformreport: to indicate to ASForm that this is a file it should use. Refer also to the list above, "ASForm provided variables".
You cannot override the From: line within a report. However, in a report you can modify the subject using the tags discussed above. One handy thing to try: Subject: Form Submission from
(assuming you asked for and required an input with the name name).
Why "tag" ASForm documents?
You've noticed by now that every file that ASForm reads has to be tagged in some way to get ASForm happy with it. There is a method behind the madness. In order to keep things more or less secure, ASForm wants to know that someone with write access put those files there -- once someone has write access, be it you or anyone else, it's too late to worry about security. A person with write access has all they need to be dangerous without needing ASForm to help them. You can't make ASForm send, say, the contents of /etc/passwd unless you have write access to it already -- in which case, you could just as easily mail the thing yourself. To keep your templates and HTML snippets secured, it's best to set them to read-only when you're not editing them. (chmod 444 filename in Unix.)
Configuration Installation Customizing
Writing Forms for
Use With ASForm
© 1999 - Art Sackett