Developing for e-gateway is extremely easy. If you can design and program a HTML form, then you need learn only a few additional rules in order to reap all of the many benefits that e-gateway offers in terms of form handling.
e-gateway is designed to use regular HTML-based templates for all of its output. Programming e-gateway is almost entirely handled within these templates. The only additional task is the editing of a small configuration file to control certain aspects of e-gateways' operation. We have implemented this methodology as it enables us to add a certain degree of security in relation to your website by hiding information that hackers and spammers could potentially use to attack your website.
The best way to learn how to program e-gateway is by example, so we'll use the documents included in the standard distribution to demonstrate e-gateway usage:
TIP: Load the "feedback.htm" file into your preferred text editor to review the source code in situ...
We begin with a standard HTML document. This document starts with a CSS (Cascading Style Sheets) property sheet, then there are a few lines of JavaScript code (the JavaScript is used for form validation - see " Client-side Form Validation" for more information on this important aspect of form design), then we have the body of the page itself (the form).
The form is entirely conventional so nothing here should be new to a competent web developer. The first couple of lines of the form definition tell the web-server what to do with the data it receives when the form is submitted (i.e. run e-gateway) and we issue our first command to the e-gateway application:
<Form Name="contact" Method="Post" Action="cgi-bin/mail_gateway.pl" OnSubmit="return validate();">
<Input Type="Hidden" Name="specification_id" Value="form_0001.config">
What we're doing here is telling the web-browser to send any data entered in the form to an application called "mail_gateway.pl" (e-gateway). The browser is also instructed to run a JavaScript function called "validate" before passing data on to e-gateway:
OnSubmit="return validate();"
then we issue a command to e-gateway:
<Input Type="Hidden" Name="specification_id" Value="form_0001.config">
which tells e-gateway that the configuration file it should use to handle this form is called "form_0001.config". We will look at the configuration file in detail elsewhere in this document.
At this point we should point out that e-gateway commands always follow this format, i.e. a hidden form field with a command (identified with a "_id" suffix) and a variable. Fields with a special significance for e-gateway also have the "_id" suffix.
The form fields are defined next: "name_id", "email_id" and "message_id". The astute reader will have noticed that these are all "special" fields (all include the "_id" suffix). "name_id" is set aside for capturing a users' name, this is classified as a special field as it is used to personalise the resulting e-mail to the user. "email_id" is set aside for capturing a users' e-mail address and is a special field as e-gateway will use this address to return an e-mail to the user. "message_id" is specifically intended to capture a body of text (comments, message, description, etc.) - this field is classified as special because e-gateway will apply its' parsing and formatting rules to this data (censorship, emoticon conversion, HTML filtering, etc). In order to provide a mechanism for e-gateway to parse more than one body of text, you should always use "message_id" as a suffix for your field names (for example: "bodytext_message_id", "email_message_id" & "TESTmessage_id" will all be interpreted as parsing fields, whereas "message", "test" & "mssg_id" would not be parsed - they'd still be processed, but only as ordinary fields). All these fields are optional even though they have special significance for e-gateway.
The final field we encounter is called "copy_id". This field is adjustable in the configuration file or within the form itself (recommended). If configured in both, then the form setting will take priority over the configuration file setting. This field is used to determine the format of e-mail returned to the user, or to prevent an e-mail being sent to him/her. This variable can be one of three values: "html" (the user will receive HTML formatted e-mails); "ascii" (the user will receive plain text (ASCII) formatted e-mails); or "no" (the user will not receive an e-mail). We recommend that you present this as a user-selectable option on the form (as we have done on "feedback.htm") rather than forcing a specific format on your users (obviously this doesn't apply if you are not returning e-mails to your users). The only time that it's preferable to use the configuration file option is when you know that ALL your users are able to receive e-mail in a certain format (on an Intranet for example), this way you have less "noise" on the form itself.
There are two other "special" variables that we haven't covered here:
- "recipient_id" - this variable allows us to target e-mails to multiple addresses from within our form. This can be used to provide a mechanism for the user to choose who his/her form submission is intended for (by department for example), or the webmaster can dictate that data received from a web form is automatically distributed to multiple recipients. E-mail addresses in the "recipient_id" need to be formatted in a special way (name [e-mail address]|format); multiple recipient details are separated with a semi-colon & space ("; "). The following code examples illustrate this:
Example 1 - Provide the user with a means to choose a recipient...
<Select Size="1" Name="recipient_id">
<Option Value="null" Selected>contact which department?</Option>
<Option Value="null"></Option>
<Option Value="Customer Services [custserv@xyzwidgets.com]|ascii">customer services</Option>
<Option Value="Sales [sales@xyzwidgets.com]|html">sales</Option>
<Option Value="Personnel [personnel@xyzwidgets.com]|html">personnel</Option>
<Option Value="null"></Option>
<Option Value="Joe A. Bloggs [webmaster@xyzwidgets.com]|ascii">the webmaster</Option>
<Option Value="null"></Option>
</Select>
(This example also illustrates the use of the "null" value. Any form input with this value is completely ignored by e-gateway, so we can safely use the null value to add to the formatting (useability) of our form.)
Example 2 - Webmaster hard-codes multiple recipients so that every form submission is mailed to all named recipients...
<Input Type="Hidden" Name="additional_recipient_id"
Value="Mr. X. Big [big@xyzwidgets.com]|html; Miss V. Small [tiny@xyzwidgets.com]|html; Joseph Andrew Bloggs [webmaster@xyzwidgets.com]|ascii">
- "value_id" - this variable provides us with a mechanism to apply formatting to a numerical value to make it more readable. Any field using the "value_id" suffix should contain numerical data only. When processed, the value the user enters is parsed and "humanised".
Example
<Input Type="Text" Name="amount_value_id" Size="10">
If a user were to enter "1234567" in a form containing this field, e-gateway would return this as "1,234,567".
As a web-developer, you can use any other field name you choose and e-gateway will simply return the user input without making any attempt to process the input data. However, because fields carrying the "_id" suffix are used to give e-gateway special instructions, you should avoid ending your field names with it unless you are issuing the commands described here.
Summary: When developing forms for e-gateway include a "specification_id" command to tell the application which configuration file to use. Use the "special" variables to control the personalisation and formatting features. Avoid using a "_id" suffix for non-command fields.
e-gateways' output and operation is controlled by two HTML documents and three templates (or two, in certain cases). The templates are regular HTML documents (but we'd strongly recommend that you don't use the conventional file extensions (".htm", ".html") for several reasons (which we'll explain in more detail elsewhere in this document), rather we suggest that you use a ".template" suffix as we have done in the standard e-gateway distribution). All of these documents contain special embedded instructions which tell e-gateway what to do.
A template is a standard HTML document. You can design templates in your favourite web-design package, or code them by hand. Note: Some web-design programs will not allow you to load the templates with their ".template" extension; rename the templates with either a ".htm" or ".html" extension, edit them in your web-design program, save them, then rename them with the ".template" extension before uploading them onto your web-server.
e-gateway searches through your templates and replaces special embedded "placeholders" with its' own output before displaying the page on the screen. The net result, totally customisable operations, with e-gateway seamlessly integrated into the design of your website.
By default, e-gateway will always try to display a "proof reading" or "approval" screen when form data is first submitted. This is good practise; it allows the user to review his/her input and edit that data before sending.
TIP: Load the "approval.template" file into your preferred text editor to review the source code in situ...
There are only two "rules" for the proof-reading template:
- Embed the exact field names used in the initial web form, encapsulated in e-gateway "placeholders" ("%%%")...
Example
<TR><TD Align="right"><Font Face="Arial" Size="3">name:</Font></TD><TD Align="left"><Font Face="Arial" Size="3"><B>%%%name_id%%%</B></TD></TR>
In this example, we have used the field called "name_id". e-gateway will replace the "%%%name_id%%%" tag here with the processed data passed to it from a form (e.g. "feedback.htm"). Regular HTML tags are used to provide formatting and layout instructions.
- The template must carry instructions to tell e-gateway what to do next (e.g. send e-mail(s)), it also needs to be able to relay the users' input back to e-gateway so that the e-mail(s) can be generated. We do this using a standard form (of which all elements except the "submit" button are hidden)...
Example
<Form Name="proof" Method="Post" Action="mail_gateway.pl">
<Input Type="Hidden" Name="action" Value="send_email">
%%%cache_id%%%
<Center><Input Type="Submit" Value="Send E-mail"></Center>
</Form>
We'll go step-by-step through this form:
- the first line sets up the form and tells the web-browser where to go when the "Submit" button is clicked (i.e. run e-gateway)
- the next line is a hidden form field called "action" - this tells e-gateway to send e-mail. Normally, when e-gateway is called, it processes a form submission passed to it and presents a "proof reading" or "approval" screen; on the proof reading screen, we have to tell e-gateway to do something else with this particular form submission (otherwise the program would loop forever, presenting repeated proof reading screens). In this particular case we're telling e-gateway that we have already performed proof reading and that it should now generate its' e-mail(s).
Incidentally, you may have realised that this method can be used to bypass e-gateways' proof reading mechanism altogether (some forms don't benefit from proof reading). Simply include this hidden command within your initial form (e.g. "feedback.htm") and e-gateway will go directly to e-mail generation when form data is received.
- on the next line we find another embedded command, "%%%cache_id%%%". This line is critically important to e-gateway (if the proof reading mechanism is being used) as e-gateway uses this placeholder to store the original form data so that it can be relayed back to itself once the preview has been approved (otherwise e-gateway would "forget" the users' submission). Without this embedded command e-gateway will fail when it tries to create its' e-mail(s).
- finally, we see a standard "Submit" button and the termination of the form with the "</Form>" tag.
For the two remaining templates ("ascii_mail.template" and "html_mail.template" in the standard distribution) only the first rule applies as we are no longer passing instructions to e-gateway (i.e. "Embed the exact field names used in the initial web form, encapsulated in e-gateway "placeholders" ("%%%")..."). These templates dictate the layout and content of e-mails generated by e-gateway.
There are a few "special" variables that can be used in the templates too. As with all other embedded variables, these should be encapsulated in placeholders (%%%variable%%%):
- "entry_date" - this variable will add the date of entry to the template (recording when the user made their submission
- "entry_time" - this variable adds the time of entry to the template
- "client_ip" - this variable adds the IP (Internet Protocol) address of the users' computer to the template (this would be useful if you wanted some means of verifying a users' identity)
- "client_address" - this variable adds the resolved host name of the users IP address to the template (for verification again); however, this variable will sometimes return nothing as not all IP addresses are mapped to a host name - if this is the case, then the field will be left blank
- "credits_id" - this variable simply adds a discreet credit and link to the e-gateway website. You are in no way obliged to use this field, but it would be nice if you did!
Templates are regular HTML documents, so why do they have a ".template" extension instead of ".htm" or ".html"?
e-gateway templates are HTML documents and as such could be accessed directly by URL. Furthermore, Internet search engine "spiders" would be able to index and catalogue them. As we don't want these pages to be viewed outside of e-gateway, we use a non-standard file extension to differentiate them from regular web pages. They should be virtually inaccessible to anything but e-gateway as a result (they are still directly accessible by URL, but the browser would try to download them as files, rather than display them).
The configuration file (see "form_0001.config") is the most important component of an e-gateway installation and is unique to every form. Without this file e-gateway will not run. If there are errors in this file e-gateway will not run...
e-gateway relies on the configuration file to tell it about things like the paths and file names of the templates, what e-mail addresses it sends e-mail to and various other important details. We are going to describe a configuration file in its' entirety below, explaining line-by-line what each variable is for and how it should be configured:
@required = ("name_id", "email_id", "message_id");
This array contains the field names of all fields that are "required inputs" on your form (that is, all those fields that the user MUST complete. These field names must exactly match the field names in the form document. For example, your form might contain the following code... <Input Type="Text" Name="username" Size="30">, in this case - if this field were required - you'd add a "username" field to the array above.
$copy_id = "";
"html" returns HTML e-mail copy to the user, "ascii" returns ASCII e-mail copy to user, "no" returns no e-mail to the user. Whilst this option can be configured here, it's much better to use your form to give your users the choice. Comment out the variable (prefix with a "#" character to comment out) and use a field named "copy_id" on your form.
$template_approval_id = "approval.template";
This variable should contain the filename of the HTML template that will be used to proof-read data input via the form. If the file is not located within the same directory as the "mail_gateway.cgi" script, then the full server path to the file should be entered here.nbsp; NOTE: All such paths should use the "/" as path separators - even when installing on a Windows NT server; never use "\" as a path separator.
$template_html_id = "html_mail.template";
This variable should contain the filename of the HTML template that will be used for HTML format e-mails generated by the application. If the file is not located within the same directory as the "mail_gateway.cgi" script, then the full server path to the file should be entered here. NOTE: All such paths should use the "/" as path separators - even when installing on a Windows NT server; never use "\" as a path separator.
$template_ascii_id = "ascii_mail.template";
This variable should contain the filename of the ASCII template that will be used for ASCII format e-mails generated by the application. If the file is not located within the same directory as the "mail_gateway.cgi" script, then the full server path to the file should be entered here. NOTE: All such paths should use the "/" as path separators - even when installing on a Windows NT server; never use "\" as a path separator.
$thank_you_id = "http://www.xyzwidgets.com/pages/thanks.htm";
This variable should contain the URL to a web page that will be displayed to the user when processing is complete.
$webmaster_email = '"Joe Bloggs" <webmaster@xyzwidgets.com>';
This variable contains the details of the default recipient (website operator(s)). This variable must be ALWAYS be enclosed in apostrophes (') NOT quotes (") and the name element should be enclosed in quotes. This variable contains the default "recipient" information. In order to comply with the relevant RFCs (standards) the variable should be formatted as follows: '"Sender Name" <sender e-mail address>'. Any deviation from these rules would have unpredictable results.
$webmaster_email_subject = "Customer Feedback";
This variable contains the text that will occupy the "Subject" field of e-mails sent to the website operator(s), NOT THE USER.
$user_email_subject = "Customer Feedback (COPY)";
This variable contains the text that will occupy the "Subject" field of e-mails sent to the website user.
$webmaster_email_format = "html";
"html" returns HTML e-mail to the website operator(s), "ascii" returns ASCII e-mail.
$sender = '"XYZ Widgets, Inc" <post@xyzwidgets.com>';
This variable contains the details that will occupy the "Sender" field of all e-mails generated by the application. This variable must be ALWAYS be enclosed in apostrophes (') NOT quotes (") and the name element should be enclosed in quotes. This variable contains the "sender" information that e-mail recipients will see on e-mails generated by the application. In order to comply with the relevant RFCs (standards) the variable should be formatted as follows: '"Sender Name" <sender e-mail address>'. Any deviation from these rules would have unpredictable results.
$smtp_server = 'mailserver.xyzwidgets.com';
This variable should contain the address of an SMTP mail server capable of mail relaying. As open mail relays are extremely rare these days (prohibiting mail relaying is the first line of defence against spammers) the best candidate for this is the SMTP server of your ISP - that is, the ISP that hosts your website and this CGI application, as this is more than likely pre-configured to relay e-mail from internal senders. Alternatively, you can enter the path to the "sendmail" application on your server if you wish to use "sendmail" and it is available to you ("sendmail" is usually available on a Unix server, only very rarely is it available on a Windows NT server).
$attachment = 'drive:/path/to/my/file.ext';
This variable contains the complete server path to any file that you wish to have added as an attachment to e-mails sent from your website (via e-gateway) to the user (not the website operator(s)). If this field is commented out (prefixed with "#") then no attachment is sent. If it is active (not commented out) then the file specified here is attached to outgoing mail. NOTE: All such paths should use the "/" as path separators - even when installing on a Windows NT server; never use "\" as a path separator.
$log_path = 'C:/xyzwidgets/website/cgi_logs/egateway.log';
This variable contains the complete server path to a logfile that e-gateway will maintain if the "$use_log" option (below) is set. This can be safely commented out if the "$use_log" option is not set. NOTE: All such paths should use the "/" as path separators - even when installing on a Windows NT server; never use "\" as a path separator.
The final part of the configuration file is a short list of options that are either on or off. Options are enabled with a "1" and disabled with a "0", as follows:
$censor = 1;
$allow_html = 0;
In the above example, the in-line censorship is enabled and HTML in form submissions is disabled. The action of each option is described below:
- $send_webmaster_email - if enabled a copy of every form submission will be sent to the "webmaster" (as defined in "$webmaster_email" above)
- $use_log - if enabled a "transaction log" will be maintained by e-gateway; recording usage of the application. If activity logging is to be used, then a path must be defined in "$log_path" (above) and the variable must be active (not commented out)
- $censor (*) - if enabled, e-gateways' real-time censorship comes into force. If "$censor" is enabled, any words entered by the user which match against e-gateways' "Abuse Database" will be removed by the system on any e-mail(s) generated. The array "@abuse" (at the end of the configuration file) allows you to maintain your own database of obscenities; when words are added you need to keep in mind that words should be enclosed in speech-marks and separated by commas. For example:
@abuse = ("bill", "gates", "microsoft", "windows");
(Censorship is case-insensitive; words can be in upper or lower case, or even of mixed case)
Using the array above any instances of the word "bill" would be replaced with "****", the word "billiards" would be rendered as "****iards". To censor more accurately, you can specify that censoring only occurs on whole-word matches. To do this you should enclose your sensitive word in braces, as in "{bill}". e-gateway will then censor the word "bill" (exact match) but would not interfere with the word "billiards". Thus your censor array might read as follows:
@abuse = ("{bill}", "{gates}", "microsoft", "windows");
- $use_crs (*) - if enabled, this option will convert all carriage returns in the users' input into HTML so that their formatting is maintained in the resulting e-mails
- $allow_html (*) - if enabled the user is able to use HTML tags in his/her form submission and those tags will influence any resulting HTML-format e-mail. If this option is disabled, then any HTML is automatically stripped from user input leaving only plain text in their submission. We strongly recommend that this option be disabled unless it is absolutely necessary; if users are able to enter HTML then there's a slight chance that they could submit malicious code
- $emoticons (*) - when this option is enabled emoticons (or "smileys") will be automatically converted from ASCII to graphical representations in any resulting HTML e-mail. e-gateway recognises and converts five smileys, which are represented below:
Options marked (*) apply only to parsed fields, i.e. those fields whose names have the "message_id" suffix.
| 
