How to Define a Form
Forms are defined using the Create a New Form page. Forms can later be modified using the Edit a Form Definition page. This document describes the form definition inputs and options.
| Form ID | This is the unique identifier for your form. It will be part of the URL to get to your form: "http://formmail.to/formID". Because it will be used in a URL, this field cannot contain any spaces or any "+", "&" or "%" characters. You can, however, use a "-" or a "_" as a word space, and you can use the "/" character, such as "myname/feedback" to distinguish that form from "myname/order". The maximum size for this field is 24 characters. |
| Password | To edit your form definition later, you will need the password entered here. Enter exactly the same password in each of the two boxes. (Since you will only see "*" characters when you type in this field, the duplicated entry helps to catch errors.) If you select the registered referals only form option, you will need this password when you register links to your form. If you select the password required form option, anyone wishing to use this form will need this password. The maximum size for this field is 12 characters. |
| Send to E-mail | Enter the e-mail address that is to receive the form data. You can enter a list of addresses, separated by commas. The maximum size for this field is 255 characters. |
| Form Title | The text entered here will be placed at the top of the form, following the "FormMail.To" logo. For a general purpose e-mail form, you might just put your name, or you might use a descriptive title for a specific type of form. The maximum size for this field is 80 characters. |
| Page <BODY | You can enter any desired HTML <BODY> tag attributes in this field, such as BACKGROUND or BGCOLOR, TEXT, LINK, and VLINK to control form colors. The maximum size for this field is 100 characters. |
| Top HTML | You can enter additional HTML that will be displayed at the top of your form page. This might be a simple greeting, an <IMG> tag to display your logo, a short description of the purpose of the form, links to your other pages or contacts, etc. The maximum size for this field is 1020 characters. There are certain internal variables that can be used in the Top HTML field, which will be replaced with their "current value" whenever the form is used. For example, %%today%% is replaced with the current date, and %%time%% is replaced with the current time. (Internal variables can also be passed as hidden form input Values.) |
| Form <TABLE | Your form will be generated as an HTML <TABLE>, and in this field you can specify optional <TABLE> parameters such as BGCOLOR, CELLPADDING, CELLSPACING, and BORDER. The maximum size for this field is 80 characters. |
| Prompt <TD | In the generated HTML <TABLE> for the form input fields, the Prompt field identifiers will be placed inside HTML <TD> and </TD> tags. You can use this "Prompt <TD" field to specify optional attributes such as ALIGN, VALIGN, and BGCOLOR. These attributes will be used for all Prompts on the form. The maximum size for this field is 50 characters. |
| Font Face | This specification allows you to specify the font face for the form, such as "Courier New", "Times New Roman", "Comic sans MS". The user's browser may or may not have the specified font installed; it's generally best to use only the standard fonts shipped with Windows. You can give a list of fonts, separated by commas, and the browser will use the first one it finds installed. The maximum size for this field is 40 characters. |
| Font Color | This controls the font color. You can use certain HTML standard names, such as "RED" and "BLUE", or you can use the HTML numeric RGB specification, such as #000000 for black, #FF0000 for red, etc. The maximum size for this field is 12 characters. |
| Font Size | This controls the font size, with "1" being the smallest font and "7" being the largest (probably unusably large for a form). Sizes 1, 2 and 3 work best. The maximum size for this field is 1 character. |
| Submit Button | This text will appear in the "submit" button at the bottom of the form. The maximum size for this field is 20 characters. |
| Transfer to URL | You can use this URL to send a user to another Web page after submitting your form (back to your home page, for example). This can be any valid "http://..." up to a maximum size of 100 characters. |
| Password reguired? |
If you click in this box (which inserts a checkmark in the box), then the
form cannot be used without a password -- the same password
as that entered above. This might be used, for example, when you intend
to use the form yourself to send messages to a mailing list (i.e., multiple
addresses in the Send to E-mail field), or when all
members of the mailing list know the password and use it to send messages
to each other.
To use this option, you must define an input field on your form with a Field Name of "password". |
| Register referals? |
If you click in this box (which inserts a checkmark in the box), then the
form can only be used when linked to from certain Web pages, rather than
when someone enters "formmail.to/yourform" in their browsers.
To register the source links, you will need the password entered above. The first time a form with this option set is accessed, FormMail.To will put up a prompt to enter the form password. If the password is correct, then the access is allowed, and so are all future accesses from the same Web page. To use this option, first put a link on your page, such as <A HREF="http://formmail.to/myform>Contact Me</A>, then access your form by clicking on this link. Enter your password, and that link will be "registered" to allow all future accesses without the password. You can register several more links this same way, up to the field maximum of 255 characters. |
| Prompt |
This text will be placed in front of the input box to identify the data
requested from the user. This field can contain HTML tags.
The Prompt is not required (for example, you might omit it from the second line of a two-line address), but if you omit the Prompt, you must provide a Field Name. If the first character of a Prompt is a "+" character, then the defined field will be placed on the same line of the form as the previous field. For example, if you wanted three fields, City, State, and Zip on one line, then the Prompts for the three fields would be "City", "+ State", and "+ Zip". |
| Field Name |
This Field Name will be used in the generated HTML as the NAME="..."
parameter of the <INPUT> tag. The Field Name (rather than the Prompt)
will also be used to identify the data in the e-mail message. That is, the
e-mail you receive will have a line labeled "Field Name:", followed by the
user's data, for each field that you define on the form.
The Field Name is not required if a Prompt is specified. In this case, the Prompt text will also be used as the Field Name. |
| Cols |
The number entered into the Cols (columns) field will specify the number
of characters (i.e., the SIZE="..." parameter) for the HTML <INPUT>
box. (If you do not enter a number, the default will be 32 characters.)
This number only controls the displayed width of the input box; it does not limit the number of characters entered by the user. Input boxes will scroll to the right if the user continues typing. (However, there is a maximum size of 8K bytes for any input field.) The Cols field is ignored for fields with a Data Type of "Select list", "Select multi", "Check box", "Hidden", or "No input". (The width of pull-down selection boxes is automatically determined by browsers from the size of the largest list item.) For Radio button data types, the Cols field can be used to control the placement of the selection boxes: If Cols is set to "1", then the Radio buttons will be displayed in a single vertical column. If Cols is set to "2" or more, then that number of buttons will be displayed on each line. To put all Radio buttons on a single line, set Cols to be equal to or greater than the number of button selections. (The default Cols size of 32 will generally put all buttons on the same line.) |
| Rows |
If a number is entered in the Rows field, then the input box will be an
HTML <TEXTAREA> (a multiple line entry area) instead of a single line
<INPUT> box, and the number of lines displayed will be the given
number. The Rows default is "1" (i.e., a standard <INPUT> box).
A <TEXTAREA> option of WRAP="virtual" will be set, which will cause automatic "word wrapping" to the next line at the right side of the box. The Rows only specifies the number of lines to be displayed in the box. The user can continue typing past the last displayed line, and there will be a vertical scrolling bar on the right side of the <TEXTAREA>. |
| Data Type |
This pull-down selection specifies either the type of HTML input box or
the type of data allowed in the field. Click on the arrow key beside
the box to see the list of Data Types, then click on the desired type to
select it:
|
Req  |
Click this check box if you want the field to be a required entry. The red arrow grapic will appear in front of the input box on the form. If the user omits a required field, an error page with the message, "(Prompt) must be entered", will be shown and the user will need to go back and enter something in the field. |
| Value | This field can be used, as a convenience to the form user, to specify an initial value for a text field. The user can change this value if desired. The Value field also has special usage for certain Data Types, as detailed for those types. (For example, this is where you provide the list of values for a "Select list" or "Radio" type.) |
| Note | Any text entered in the Note field will be displayed on the righthand side of the input box. Use this field to note any special requirements or comments about the input field. For example, you might put "Required" as the Note for required fields, or you might document the expected format for special fields such as telephone numbers or Social Security numbers. This field can contain HTML tags. |
If the form definition is successfully saved, you will receive a page
noting the URL and a "Click here to try it" link. Click that link to view
and check your form.
Regular expressions use "meta-characters" to specify the format of the input. The regular expression "meta-characters" that are supported are:
| ^ | Beginning of string (i.e. the following pattern must match the string starting at character number 1). |
| $ | End of string (i.e. the preceding match must be at the end of string's value). |
| . | Match any single character. |
| * | Match zero or more occurrences of the preceding character or [...] character class. |
| ? | Match zero or one occurrence of the preceding character or [...] character class. |
| + | Match one or more occurrence of the preceding character or [...] character class. |
| [...] | Match a single character to any one of the characters in the specified list (a "character class"), such as [ABC]. |
| [a-z] | Match a single character to any one of the characters between the two characters separated by "-", e.g. [0-9] would be any digit, or [A-Z] would be any uppercase alphabetic. You can include several pairs in the same list, such as [a-zA-Z0-9] to match any alpha-numeric character. You can mix character ranges with lists, such as [ABC0-9] to match "A", "B", "C", or any digit. |
| [^...] | Match any character that is not specified in the list for the character class, such as [^a-zA-Z0-9] to match any non-alpha-numeric character. |
| {n} | Match the preceding character or character class exactly "n" times, e.g. [0-9]{8} would match exactly eight digits. |
| {n,} | Match the preceding character or character class "n" times or more, such as [0-9]{8,} to match eight or more digits. |
| {n,m} | Match the preceding character or character class at least "n" times but no more than "m" times, such as [0-9]{8,10} to match eight, nine, or ten digits. |
| | | Pattern "or" separator. Match either the preceding pattern completely or the following pattern completely. May be used multiple times. |
| \t | The ASCII tab character. |
| \r | The ASCII carriage-return character. |
| \n | The ASCII linefeed ("new line") character. |
| \ | "Escape", take the next character "literally" as part of the pattern, not as a special character. For example, \* means the asterisk is in the pattern to be matched, instead of the meaning shown above. Use \\ to specify the backslash itself. |
Pattern Examples:
A Social Security number has a particular format: three digits, a hyphen, two
more digits, another hyphen, then four digits. This format can be
validated with this regular expression:
^[0-9]{3}-[0-9]{2}-[0-9]{4}$
The "^" as the first character means that the remainder of the pattern must
match starting with the first character of the input data. (Otherwise, a
pattern can be matched anywhere within the input.) Most of your
"Validate s/" patterns will probably require the "^" character (and the
end-of-string "$" character) to avoid extraneous data before or after the
matched pattern.
Following the "^" is a "character class" of "[0-9]", which means to match any character between "0" and "9", inclusive, which is to say any digit character. Following the "[0-9]" is "{3}" which means that the preceding character (or in this case, a character class) is to be matched exactly three times. Following that is a literal hyphen ("-"), with no following qualifiers, so this means that a single hyphen must be present. The remainder of the pattern specifies that there should be exactly two more digits, followed by another hyphen, followed by exactly four digits. The "$" sign at the end means that the end of the data is expected immediately following the last four digits. Like the "^" at the beginning, this prevents any extraneous data in addition to the matched pattern.
As a more complicated example, a standard US phone number has a three-digit area
code, a three-digit exchange code, then four digits. But several different
conventions are used for the format of a phone number, such as optional
parentheses around the area code and hyphens or spaces between the groups.
The following pattern will match any of the typical formats, while failing to
match an invalid phone number:
^(?[0-9]{3})?[- ]?[0-9]{3}[- ]?[0-9]{4}$
Again, the "^" as the first character means that the remainder of the pattern
must match starting with the first character of the input data.
The next character, "(" is
immediately followed by a "?" which specifies zero or one occurrence of the
character (i.e., it is an optional character). Next, "[0-9]{3}" means that
exactly three digits should be present. Then there
is another optional ")". Following that, the specification "[- ]?" means
that a single hyphen or space may or may not be present. Similarly, the rest
of the pattern specifies a three-digit group followed by a four-digit group,
perhaps with a hyphen or space between them. And again, the last character of the
pattern, "$", means that the end of the input data is expected after the
four-digit group, so this pattern will not match if extra characters or digits
are entered.
The pattern above will match any of the following phone number formats: (719) 555-1212, (719)555-1212, (719) 555 1212, 719-555-1212, 719 555-1212, 719 555 1212, 719 5551212, or 7195551212.
The "$" end-of-string meta-character can be used by itself as a valid pattern for
an optional field. (That is, an empty field will immediately match the
end-of-data meta-character.) If a field is optional but must have a certain
pattern if it is entered, you can use the "$" followed by the "|" ("OR bar")
separator, followed by the required pattern. For example, this pattern will
allow an empty field but will validate that, if given, the input includes only
"alphanumeric" characters (i.e., upper or lower case alphabetics or numeric
digits):
$|^[a-zA-Z0-9]*$
Internal Variables
There are some special variables that you can use in your form to dynamically
insert values that are known to the FormMail.To program. These variables can be used
in the Top HTML field to be displayed at the top of
the page, or they may be used in a Value
specification to initialize a form input field. (If you want to pass one of
these variables with your e-mail message, but don't want the form user to see
them, set the Data Type to "Hidden".) The Top HTML and the
Value column are the only places these will work.
| %%today%% | Current date in the format "Month DD, YYYY", where "Month" is the full name of the current month, "DD" is the one- or two-digit day of the month, and "YYYY" is the four-digit year |
| %%date_short%% | Current date in the format MM-DD-YYYY, where "MM" is the number of the current month, "DD" is the number of the day, and "YYYY" is the four-digit year |
| %%date_ymd%% | Current date in the format YYYYMMDD, where "YYYY" is the four-digit year, "MM" is the number of the current month, and "DD" is the number of the day |
| %%year%% | Current year, four digits |
| %%month%% | Current month, one or two digits. (Use %%format("0#", %%month%%) to force two digits) |
| %%day%% | Day number in current month, one or two digits (Use %%format("0#", %%day%%) to force two digits) |
| %%monthname%% | Full name of current month (e.g., "September") |
| %%weekday%% | Full name of current day of week (e.g., "Monday") |
| %%time%% | Current 12-hour clock time on the FormMail.To system, in the format HH:MMam or HH:MMpm, where "HH" is the hour and "MM" is the minute |
| %%time24%% | Current 24-hour clock time in the format HH:MM, where "HH" is the hour and "MM" is the minute |
| %%http_referer%% | The URL of the document that was used to link to the form |
| %%remote_host%% | Host that the user is running on (may be a node name, but commonly is just the numeric Internet address; no "reverse DNS lookup" is done) |
| %%remote_add%%r | Internet numeric address (nnn.nnn.nnn.nnn) that the user is running on |