Online Services Form Mailer How To

State of Oregon - Online Services

155 Cottage St NE Salem OR 97301

Phone: 503-378-2135 Fax: 503-378-5543

Form Mailer How To

The services below are provided to users of Online Services for use in web pages on this server. Online Services does not provide consulting, development, instruction or training for any of these services, or web page development in general. Please use the documentation provided with each of these services for support. If you feel there are errors in any documentation or problems with any of these services, please contact Online Services Support.

Online Services shall in no way be responsible for any damages or losses resulting from the use of any of these services. Please refer to the Online Services User Agreement for further details on usage policy.

This document explains how to set up an HTML form that will e-mail user input to you at a specified address. Please be sure to read the requirements section. The options section provides information on using and configuring your form.

Overview

The form mailer allows you to have user input from a form e-mailed to you at a specified address. The form can be inserted into any HTML page using specific HTML tags to create input fields.

Requirements

1. The browser using your form must supply the web server with certain environmental variables. Browsers that do not supply these variables will not be able to use your form. Fortunately, most browsers (Netscape, MS Internet Explorer, Lynx) supply these variables.

2. Your opening <form> tag must be:

<form method="POST" action="/cgi-bin/formmail.cgi">

Note: POST should be uppercase or some browsers may not work properly.

3. You must specify an e-mail address to send your form input to in a special configuration file (see the Configuration File section at the bottom of this page).

4. Do not use the following extensions on your own input field names as they are reserved for use with the form mailer options.

_def
_del
_int
_req
_sort
_sys

Options

You may place your form anywhere under your public_html directory. When your form is submitted, the input will be e-mailed to the specified address. Your form may consist of any number of input fields. A sample form is provided as a reference in getting started.

There are a variety of options that can be used by adding extensions to an input field name within a hidden input field. These options can be placed anywhere between your opening and closing <form> tags.

1. You can use the _sys variables to change system settings.

url_sys redirects the user to a specified URL after the form has been submitted.

<input type="hidden" name="url_sys" value="http://dialoregon.net">

You must specify the complete URL (i.e. http://dialoregon.net/...), even if the page is located in the same directory as your form. If you do not set this variable, a default message will be displayed.

subject_sys can be used to specify the e-mail subject line.

<input type="hidden" name="subject_sys" value="User Input Form">

delimit_sys can be used to specify a delimiter for the input fields in the body of the e-mail message. By default, newline ('\n') is used. '\t' can be used for tabs.

<input type="hidden" name="delimiter_sys" value="|">

names_sys can be used to specify the return format. By default, each input field is returned in the format "name=value". You can suppress the name (i.e. return only the value) by setting the names_sys variable to 0.

<input type="hidden" name="names_sys" value=0>

ip_sys, browser_sys and date_sys can be used to return the ip address, browser type and date respectively. For example, if you want to know the browser type of the user, add

<input type="hidden" name="browser_sys">

to your form. You can specify the return order of these variables with the _sort extension (e.g. ip_sys_sort, see Option 4 below).

2. You can add required fields to your form with the _req extension. For example, to make the input field "age" a required field, simply add

<input type="hidden" name="age_req">

to your form. If the input field is left blank, an error message will be displayed. You can also specify a value for this tag which will be displayed as the input field name in the resulting error message. DO NOT try to use this extension with the default extension _def (see option 6 below) as _req requires user input from the form and does not consider a default value to be user input.

3. You can make an input field accept only integer (0-9) values with the _int extension. For example, to make the input field "age" accept only integers, add

<input type="hidden" name="age_int">

to your form. If the user enters any non-integer characters, an error message will be displayed. You can also specify a value for this tag which will be displayed as the input field name in the resulting error message.

4. You can specify the order in which the user input is returned to you with the _sort extension. The value should be the order of the field relative to the other fields in the form. For example, if you want input field "age" returned as the 3rd field, then you would add

<input type="hidden" name="age_sort" value=3>

to your form. If you are going to use _sort, you should use it on all of your input fields or you will get unreliable results.

5. For multi-valued input fields such as multiple select lists, you can specify the delimiter you want to use between each value with the _del extension. For example, to use a colon to separate each value selected in a select list named "places", add

<input type="hidden" name="places_del" value=":">

to your form. By default, a comma will be used. '\n' can be used for newline and '\t' for tab.

6. A common problem with input types such as checkboxes is that they only pass a value if they are checked. In order to create a default value for these input fields, you can use the _def extension. For example, to make the checkbox variable "age" have the default value "N/A" if it is not checked, add

<input type="hidden" name="age_def" value="N/A">

to your form. Now "age" will have a value regardless of whether it is checked or not. Default values will only work with input types that do not pass a value if they are not selected (i.e. checkboxes, select lists). DO NOT try to use this extension with the required extension _req (see option 2 above) as _req requires user input from the form and does not consider a _def value to be user input.

Configuration File

This file is required in order to use the form mailer. Your form mailer will not work until you follow the directions below.

Each web page you create that includes our form mailer must have an associated configuration file. The configuration file must be placed in your main web directory (public_html), regardless of where the actual web page is located. Your configuration file will be the name of your web page with the extension .cfg added to the end of the file. For example, if your web page is named form.html, then your configuration file will be named form.html.cfg.

In your configuration file, you must define the email address that your form mailer input will be sent to. To do this, create a line in your configuration file with the following format:

mailto:email-address

where email-address is the email address you want your form mailer input to be sent to.

As an example, let's say we create a web page to use with the form mailer with the name request_info.htm. After we create the actual form on our web page and upload our web page to the web server, we must then create another file named request_info.htm.cfg and add the following line:

mailto:email-address

where email-address is replaced with the actual email address we want our form mail input sent to. Then, we have to upload our configuration file (request_info.htm.cfg) to the web server.

Online Services is a division of the Technology Support Center - State of Oregon