Output Page Keywords

Receipt Keywords

RECEIPT_SUBJECT Sets the "Subject:" line of the e-mail receipt.

RECEIPT_FROM Sets the "From:" line of the e-mail receipt.

TEMPLATE_MAIL Specifies the template to use for the e-mail message to

TEMPLATE_RECEIPT Specifies the name of a template to use for the e-mail

TEMPLATE_WEB Specifies the name of a template to use for the web page

The only required fields for WebMailer Pro DB to e-mail a simple form are the 'RECIPIENT' and 'EMAIL' fields. If the 'RECIPIENT' is not specified, then the default address that was set during installation is used.

Note the difference between 'EMAIL' and "RECIPIENT': 'EMAIL' specifies the e-mail address of the end user who filled out the form. 'RECIPIENT' specifies the e-mail address to which all form results are sent; this is usually the address of the webmaster or other person who is collecting that particular form’s data.

Other fields may be included in the form depending upon the overall functionality you wish to incorporate into your site. Using just the basic variables, a simple guest book can be created. An example guest book is included with the installation to demonstrate the use of basic form settings. This example form was installed into a directory you chose for sample files during installation. To use the form, open the file with any text or HTML editor and change the recipient field to your e-mail address. Each of the redirect fields will need to be modified as well to reflect the path on your web server where the samples were installed.

The form asks for the name, e-mail, and comments of the guest. Required fields are the name and e-mail. Upon success, the guest's browser is redirected to a thank you page. After modifying the RECIPIENT to contain your e-mail address, open a browser and type the following on the address line

to try out the form. This example also illustrates the use of redirects to the user's browser and the fields that are required. Experiment and make changes to the hidden form values to observe their changes on the form processing and output. Try out different options with this form until you feel comfortable passing values and settings to the program.

A template is a file that WebMailer Pro DB uses to build custom e-mail and web pages from the data that the user submits in the form. These pages can be used to provide customized responses to form input. Templates are stored in a subdirectory named GEOCEL\TEMPLATES beneath the directory where the executable file is located. If you wish to specify another directory as the root directory for templates, refer to Appendix B for making this change in the WEBMLR.INI file.

WebMailer Pro DB uses a very simple template language that reserves a few special characters to signify form and environment values.

* (asterisk)

In order to display any of the reserved characters as actual text to display, "escape" them with a '\' (backslash) character as is done C and Perl.:

Syntax: \special character

Sample: x \+ y

Output: x + y

Creating templates can be accomplished using any standard text editor such as Notepad. After the template is created, it needs to be saved in the templates directory; unless you have specified a different directory by modifying the WEBMLR.INI file (see Appendix B), this is the subdirectory GEOCEL\TEMPLATES below the directory where the WebMailer Pro DB executable file is located. Any file extension can be used as long as the file name specified in the HTML form matches the name of the template.

In order to use the new template, you will need to pass the name of the template file to WebMailer Pro DB through a hidden input type form field within an HTML form. WebMailer Pro DB will parse the template file substituting form values for variables and return the complete page. Examples of each type of template follow:

E-Mail Templates can be used for the return receipts sent to users that fill out your form or to the recipients of the e-mail message. For example, a simple form for a feedback page would be:

.....

If the user submits:

First_Name = "John"

Last_Name = "Doe"

Email = "johnd@anon.com"

Comments = "I really like your site!!"

And the template "email.txt" is:

Then the form values would be translated to an e-mail message similar to this:

…

Creating e-mail Receipts for visitors is very easy as well. First, you will need to include a hidden form field specifying that you wish to return a receipt. Then you will need to setup the name of a template to use for the receipt as shown below:

A formatted receipt will then be sent to the visitor using the receipt.txt file. Any template file specified in the form must reside in the templates directory.

Web templates are basically the same as e-mail templates except that the template file includes HTML formatting codes in addition to the control characters. The control characters do not conflict with HTML so you can preview the layout of the file with any browser. First, specify the values in the form as follows:

If the user submits:

First_Name = "John"

Last_Name = "Doe"

Email = "johnd@anon.com"

Comments = "I really like your site!!"

and the template "response.htm" is:

Then the user would see the following displayed in their web browser:

If visitors fail to fill in all of the required form fields, a web template can be used for this page. A hidden field will need to be added setting the "TEMPLATE_MISSING" to the name of the template.

Currently, WebMailer Pro DB's Template Language supports one advanced feature: conditional expressions. Using conditional expressions, you can tailor the response that is returned based on the user's input. WebMailer Pro DB supports the following types of conditional expressions:

To use a conditional expression in WebMailer Pro DB, insert a conditional block in the appropriate template file as follows:

[ <conditional expression> ]

Conditional blocks can be nested.. The statements inside of a conditional block behave the same as expressions outside the block. Variables inside of the square brackets for the conditional expression should not be delimited by '%' signs.

Lets take an example to illustrate the use of conditionals:

On your Web Site, you sell mailing lists. When a user on your site decides they want to purchase a mailing list from you, you can offer several means of delivery. So, in this example, you're offering delivery via e-mail, fax, or U.S. Postal mail. Depending upon which type of delivery the person chooses, you want to provide them with a customized receipt. The relevant form values for this example would be:

The following segment of template code could be used in the e-mail receipt template:

Note that form variable names are not enclosed with '%' characters inside of the conditional square brackets. If the condition inside the square brackets ([]) is not met then no text will be output.

For example, if the visitor chooses regular US Postal mail as the delivery type, then the output would be:

WebMailer Pro DB supports writing HTML Form results to almost any database using the server’s ODBC (Open Database Connectivity) drivers. By default, drivers are provided for Microsoft Access, Microsoft Excel, CSV Text files, and Microsoft SQL Server. If you have another database type, and you cannot find a compatible ODBC driver in the Control Panel under ODBC, contact your database vendor for their latest version.

In order to save the results of your forms to a database, you will need to specify a Database Template for each form on which you wish to enable this feature. A Database Template should be stored with the other templates used to process a specific form. The Database Template is the file that defines the Table and Database to which to write, and associates Columns (fields) in the database with HTML Form variables.

In order to use WebMailer Pro DB with ODBC, an ODBC Data Source must be created for the database that is to be used. When creating the ODBC Data Source Name (DSN), be sure that it is created as a System DSN instead of a User DSN. User DSNs are only available in the context of the user logged into the system. Since the Web Server usually runs as a different user (except on Windows 95), you must create it as a ‘System Wide’ resource in order to use it.

WebMailer Pro DB writes to a database only when the Database Template is specified as an HTML Form variable named TEMPLATE_DATABASE.

Tables and Field Names used with WebMailer Pro DB cannot include spaces. Most databases do not allow spaces in names, however Microsoft Access does. The underscore ‘_’ character is usually a suitable replacement.

Below is an example of a Database Template file. There are two parts; the first is named [DATABASE]. [DATABASE] is a keyword that lets WebMailer Pro DB know this is a valid Database Template. The second section is named after the TABLE value specified in the [DATABASE] section. In this example, TABLE = TheTable; thus, the second section is named [TheTable]. Be sure to leave one blank line between sections.

DSN = GEOCEL

USER = username

PASSWORD = password

TABLE = TheTable

FIELDS = NAME, EMAIL, CITY, STATE, ZIP

NAME = FULL_NAME

EMAIL = EMAIL_ADDRESS

CITY = CITY

STATE = STATE

ZIP = ZIPCODE

DSN – ODBC Data Source as it is named in the System DSN section of the ODBC Administrator.

USER – Not always necessary, but is needed if your Database requires you to log in with a Username or Username and Password.

PASSWORD – This option is to be used when you need a Username and Password to log into the Database specified by the DSN.

TABLE – The Database Table into which data is to be inserted. Some Databases allow insertions into Queries and Views, however, you’ll need to refer to your specific Database documentation to verify this feature and/or determine any limitations.

FIELDS – Comma separated list of all Database Fields (Columns) into which data is to be inserted. These must of course be valid fields for the Table specified.

Other Settings – These settings associate HTML Form variables to Database Fields listed in the FIELDS setting above. This will map each Field to a HTML Form variable. EMAIL=EMAIL_INPUT would insert the contents of the HTML Form variable EMAIL_INPUT into the field named EMAIL in the specified table.

Notes: AutoNumber or Identity type fields should generally not be mapped to a Form Variable. Empty Fields result in an Empty String being inserted, instead of a NULL value. Some database engines may interpret this as a NULL, especially for Numeric and Date types.

Some databases will require data-type specifiers for certain data types. The default data type is a character string. Some database engines (and/or their counterpart ODBC drivers) need the proper datatype defined before the data is inserted into the database.

To specify a datatype for a particular column, in the [Table] section of the Database Template, append "_DATATYPE" to the name of the field and add it as another entry. Set the value to the appropriate datatype as specified in the table below:

In the following example, assume the DESCRIPTION field is defined as a Memo field in a Microsoft Access database. Because the ODBC driver for Microsoft Access only accepts 255 characters in a character string more than that cannot be added with specifying the datatype. In this configuration, a very long string (possibly something entered into a <TEXTAREA> field) can be inserted into this database.

FIELDS = NAME, EMAIL, DESCRIPTION

NAME = FORM_NAME

EMAIL = FORM_EMAIL

DESCRIPTION = FORM_DESCRIPTION

DESCRIPTION_DATATYPE = -1

HTML Form results can also be saved to a plain text or HTML file. This feature can be used to create a file that can be easily imported into a database or spreadsheet. It can also be used to create a growing text or HTML file, which can be displayed anywhere in a web site. For example, it is possible to display users who have filled out a guestbook or comment form. Because this is a text file, it is simple to create any type of text based formatting.

Note: Text templates consist of up to 6 files. First, the Textfile Template specifies names for all of the other templates which are to be used. The other files should be in the same directory as the Textfile Template. Below is an example of a Textfile Template, and a simple description of the other files:

Below are the contents of a sample Textfile Template:

HEADER = header.txt

DETAIL = detail.txt

FOOTER = footer.txt

WORKFILE = workfile.txt

DESTINATION = destination.txt

HEADER – The header is a file containing any text to be used as a Header in the final or destination text file.

DETAIL – The detail file is a template file that specifies the format of the data that is repeated for every record written to the final or destination text file. You may use any of the template syntax described in Section 5.

FOOTER – The footer is a file containing any text to be used as a Footer in the final or destination text file.

WORKFILE – If a HEADER and/or FOOTER exist, then it is necessary to specify a WORKFILE. The workfile holds the details of all prior submissions. This file, and the contents of this file will be automatically generated by WebMailer Pro DB. If any information needs to be changed or removed from the destination or final file, it is best to edit this file to change the information.

DESTINATION – The destination is the text file which should be properly formatted with an optional header and footer and all detail information. This file can be edited directly if no HEADER and FOOTER are being used. Otherwise, edit the WORKFILE because the DESTINATION is overwritten with each HTML Form submission.

For example, to create an HTML guestbook for people to sign:

[TEMPLATES]

HEADER = HTMLHEAD.TXT

DETAIL = HTMLDETAIL.TXT

FOOTER = HTMLFOOT.TXT

WORKFILE = HTMLWORK.TXT

DESTINATION = C:\WEB_SERVER\DOCS\GUESTBOOK.HTM

Step 3: Create the Header file:

Step 4: Create the Detail file:

Step 5: Create a Footer file (Be sure to close anything opened in the header):

Now, submit the form and after one submission there should exist a file called GUESTBOOK.HTM in its appropriate directory.

If any problems come up, the Log file generally will report missing files, etc…

If no workfile is specified, then WebMailer Pro DB can still process textfiles. Generally, with a workfile specified, the workfile is appended each time an entry is added. Then the Header and Footer are added to the workfile to make the final file. If any information needs to be removed from the destination file, it is best to remove the information from the workfile since the destination file is overwritten with each new entry.

<BODY BGCOLOR="#FFFFFF">

To correctly display the tag, 'escape' the pound sign.

<BODY BGCOLOR="\#FFFFFF">

If you have any questions about this program, you can receive free support via email at:

Technical support questions are usually answered within 24 hours. Please be specific and include web server and version, and all relevant code (HTML pages, templates). Support can also be obtained over the web at:

If the problem cannot be resolved via email, you may contact technical support at

(512) 485-7550.

Thank you for purchasing WebMailer Pro DB.

CGI: Common Gateway Interface. This interface allows a web server to communicate with an executable program running on the same computer. Typically, it is used to pass information for further processing and delivery, and to accept information for display in the user's web browser.

CGI-BIN: This is the directory in which all CGI executables typically reside. The directory is created when you install your web server, and may be called by another name.

E-mail: Electronic Mail. A standard allowing users on various computers connected to a network to send messages to each other. Some implementations of e-mail allow for attachments to send images, or other non-plain text files.

HTML: HyperText Markup Language. This is the "language" of the World Wide Web used to compose web pages allowing for navigation (i.e., links), limited layout control and font control, image integration, as well as other more advanced functions.

HTTP: HyperText Transfer Protocol. A standard network communications protocol web servers and web browsers to use "talk" to each other.

Internet: A huge network connecting computers all over the world allowing them to communicate with each other. E-mail and the World Wide Web are just two of the many services that use the Internet as their transportation medium.

URL: Universal Resource Locator. This is a generic term for any item that can be retrieved over the Internet. It can be a World Wide Web page, and FTP file archive, a newsgroup, a gopher database page, etc.

Variables: These are "place holders" used in programs or templates. They can be used to hold values that can be assigned at any time, and then displayed as the user desires.

Web Browser: A program that acts as a client to a web server. It is the "Window" into the World Wide Web. It requests pages from a web server using the HTTP protocol.

Web Server: A program that communicates with a web browser, and "serves" pages requested of it over the Internet using the HTTP protocol to web browsers requesting those pages.

World Wide Web: The combination of web servers and web browsers running over the Internet.

The program uses a small initialization file to store constant values that will be needed every time the program is called. This file is named WEBMLR.INI and is located in the same directory where the executable is located. To modify any settings, open the file with a text editor and make any necessary changes. A sample configuration after a typical installation is below:

Specifies which web sites can point to your WebMailer Pro DB executable. Typically, you will put only your site’s address (e.g., www.mydomain.com) in this string; this prevents unauthorized users from using your site to process forms without your permission. You can grant multiple web sites permission by specifying multiple referers in this string, as in the example .INI file above.