MANUAL

Installation

We made installation as easy as we could. If you prefer not to do it yourself, we offer professional installation for our Master Series CGI software.

IMPORTANT: Use an FTP program for uploading files, creating directories, and changing permissions. Upload files as plain text format, not as binary.

CuteFTP and WS_FTP for Windows, and Transmit and Fetch for Macintosh, are among the many FTP programs that allow you to upload files as both plain text format and binary format, and allow you to change directory and file permissions.

Installation takes 4 simple steps

Upload the program files to your server into a directory that can run Perl CGI programs. Upload them as ASCII/plain text.
Once uploaded, set the permissions of the program files to 755 (read/write/execute read/execute read/execute).

If you're using an FTP program to set permissions, use the following as a guide:

Owner: read-write-execute
Group: read-execute
Other/World: read-execute

If you're using telnet or SSH, change directories to the location of the program files and, and for each file, type
```
chmod 0755 _______
```
where the underscore is replaced with a file name.
Type the URL of MasterFormV4CP.cgi into your browser.

You'll be asked to provide a password for future access.

Once in the control panel, click "Email Configuration" and verify the Master Form V4 initialized information.

Although optional, it is suggested that you provide an email address where notifications can be sent. The emails sent to you when an error occurs can contain more and better information than the sometimes generic information sent to the browser. The emailed notification information is for you. The browser error message is for your site visitor.

Click "Update Email Configuration"

You may wish to browse the control panel some more right now, or wait until later. In either case, see The Control Panel for information about the features waiting for your discovery.
If you plan to use database or email templates located in a directory other than where MasterFormV4.cgi is installed at, you will need to create a new subdirectory.

Name the directory as you please. (For this manual, we will assume the directory's name is "work".) Set permissions for the directory to 755.

If you uploaded MasterFormV4.cgi into a subdirectory named "mf4", this is how the directory structure might look:
```
cgi-bin |
        | mf4 |
              | work
```
Master Form V4 will create directories as needed (on most servers) for databases and uploaded files.

When Installation is Problematic

Several options exist for help with troubleshooting installation and, indeed, with any aspect of Master Form V4. The Troubleshooting section, below, has a list.

Troubleshooting

For help with installation, unless you're an experienced installer, the Frequently Asked Questions page should be consulted first. If that doesn't solve the problem, use the forum or personal contact page, URLs below. (Professional installation services are available, if needed or wanted.)

The Ask the Master Series CGI Q&A Forum! is a place to get questions answered that you think others might also be interested in.

For answers to questions that are not appropriate for the Ask the Master Series CGI Q&A Forum!, use our personal contact page.

Troubleshooting Email Sent From Scripts is a good article about things that might prevent scripts from sending email or prevent email being sent from arriving. Reasons Why Scripts Won't Send Email also has good email troubleshooting information, although most of it is covered in the prior article.

The ZIP file of information and examples might help with understanding and answer some questions.

For other support requirements and for general information relating specifically with how to use or take the most advantage of Master Form V4, see the Master Form V4 Support page and its links.

The Control Panel

The Master Form V4 Control Panel has detailed information about the use of, and suggested values for various preferences. The information in this manual is supplementary and more of an overview nature. See the control panel pages themselves for specific details,

Here is a list of control panel links from the Main Menu and an overview of each.

Email Configuration

Only the location of sendmail is required on this page

Although optional, it is suggested that the rest of the sections on this page be utilized:

An email address where notifications or "problem alerts" can be sent. The emails sent to you when an error occurs can contain more and better information than the sometimes generic error information sent to the browser. The emailed notification information is for you. The browser error message is for your site visitor.
An email address where update notices can be sent. Master Form V4 will likely be updated from time to time. Users will request features that we want to include in the software. The auto-submission prevention code may require updating if persistent crackers find a way around the current preventions. Bugs may be found that need to be squashed.

When you provide an update notification email address, that address is stored in the configuration file on your server only. Our server does get notification of your preference. When/If an update is available, our software nudges your software and your software sends an email to you. You determine the content of that email (it would be tempting spammers if outside software could determine the message sent to you).

Blocking IP Addresses

IP addresses can be blocked. Specific IP addresses can be specified. Ranges and wild cards can be used.

Master Form V4 can generate a message for users whose IP address is blocked. Or, you can provide a web page for that purpose. The web page you provide may have a placeholder to print the blocked IP address being used.

Banned Words/Phrases

Certain words and phrases can be blocked. Partial words and exact phrases can be specified.

Master Form V4 can generate a message for users who use a banned word or phrase. Or, you can provide a web page for that purpose. The web page you provide may have a placeholder to print the offending word/phrase that was used.

Auto-Submit Protection

The automatic submission protection is designed to be transparent to the user.

Master Form V4 considers several things that might indicate automatic submission. It is likely that once in a while a valid user will be flagged. In that case, a nice message can let the user know what is going on and how to get the form submitted.

Two things must happen to enable auto-submission protection.

Certain code must be pasted into each form using this installation of Master Form V4. The code is provided on the Auto-Submit Protection control panel page — copy 'n paste. PHP, SSI, and JavaScript code are available; use whichever is best for you.
A certain checkbox on this page must be checked to enable auto-submission protection. Once that checkbox is checked, all forms submitted to that installation of Master Form V4 are immediately subject to the protection mechanism.

Whether checked or unchecked, the auto-submission protection checkbox effects all forms submitted to Master Form V4.

If you have some forms that require auto-submission protection and others that you prefer not to have it, the only recourse is to make a second Master Form V4 installation. (The license allows multiple installations so long as all are installed on the same domain.) One installation can then service forms with auto-submission protection and the other can service forms without.

Date Placeholder Values

Specify your preferred spellings for months and days of the week. These are used when dates are inserted into email, database, and "thank you" page templates.

Web Page Form Locations

If you ever wish to know the locations of forms that submit to Master Form V4, this is the place to look.

Sequential Numbering

When you utilize the sequential form submission numbering feature, this page can provide information about recent activity.

(See the discussion of the hidden fields use_numbering_key and use_numbering_start for more information.)

Database Module Choice

If compatible modules in addition to the standard SDBM_File are available on your server, you can select the one you prefer. Different modules have different capabilities.

The default SDBM_File should be sufficient unless you have thousands of forms scattered about the Internet or you have thousands of form loads every day.

If you change the database module, the information in all relational databases will be cleared in anticipation of using the new module. See the control panel page for more information about this.

Maximum Data Size

If you wish to limit the amount of information that may be submitted, including size of file uploads, here is where you specify the limit number.

Change Password

Click to change the control panel password.

If you ever lose or forget your control panel password, find file p.cgi in the MFv4 Data directory. Delete p.cgi and the next time you access the control panel, it will ask you to assign a new password for future access.

Log Off

Click to log off.

Tech Support

This link goes to a page at willmaster.com with lots of support-related information, including the means of asking for personal help.

Making Forms

If this is your first time using Master Form V4, click here to download a ZIP file of information and examples using using different Master Form V4 features.

If you are unfamiliar with making web page forms, please see the "HTML Form Tutorial" article.
"The Inner Workings of Master Form V4" can give you a better idea of how Master Form V4 works.
Many examples come with the above ZIP file, including elaborate multi-page and upload forms as well as simple feedback forms.

It is impossible to provide an example of everything Master Form V4 can do. With all it's features, the number of different things it can do may stretch the definition of finite.

Form field names

You can name your own form fields anything you like, with two exceptions:

The name may not contain illegal characters.
The name may not be reserved by Master Form V4 for special instructions

Here is a list of Master Form V4 illegal characters for field names:

Character	Name of character
:	Colon
;	Semi-colon
,	Comma
"	Double quote character
=	Equal sign
&	Ampersand
?	Question mark
<	Left angle bracket
>	Right angle bracket
(tab is invisible)	Tab character

If JavaScript will be used to consult or manipulate the form field names, the names may contain only letters (Aa-Zz), numbers (0-9), and the underscore character (_), and the name must begin with a letter.

Form field names are case sensitive.

Here is a list of Master Form V4 reserved field names:

Form field names reserved for sending specific instructions or internal field names used by Master Form V4.	Template placeholders reserved to insert specific variable data.
conditionalattachment conditionalrequired dbfile EmailAddressSeparator emailfields emailtemplate emptyrequired errorpage filetemplate flattenfields flattenreplacement flowto hidden JSfields nocarry paragraphize redirect requiredfields selectionmaximum selectionminimum submitget submitpost uploadedfilesaveinfo use_number use_numbering_key use_numbering_start	ATTACH ALLME AMPM AMPMHOUR AMPMHOUR2 COUNT DAY DAY2 EMAILS ERROR_MESSAGE HEADER_TIME_STAMP HOUR HOUR2 INSERT INSERT_HIDDEN_FIELDS IP LONGMONTH MATH ME MINUTE MINUTE2 MONTH MONTH2 REFERRER SCRIPT_LOCATION SECOND SECOND2 SELFDOMAIN SeparateWith SHORTMONTH SYSTEMTIME UPLOAD WEEKDAY YEAR YEAR2

Hidden Fields

Hidden fields are an important tool for sending instructions to Master Form V4.

Location Related Hidden Fields Values

The instructions contained in some of the hidden fields are the location of a template, of a page, or of a file name. Depending on the hidden field, one or both of the following formats can be used to specify the location:

Absolute URL

An absolute URL is an http://... URL. Not all hidden form fields that specify a location can use this format. There are four reasons why an absolute http://... URL might not be appropriate for certain hidden fields.

The location tells Master Form V4 where to create/update a file (as opposed to retrieve a file). Absolute http://... URLs can only retrieve files.
The location is a URL where browsers can not load web pages or retrieve text files (in a cgi-bin, for example).
The location of the web page is in a password protected area. Master Form V4 does not know how to negotiate access to password protected areas.
The location of the web page or text file is on a secure server — IF the web page or file is to be used as a template. Redirects to a secure server URL are okay, as that is simply redirecting a browser. But templates can't be retrieved from a secure server as Master Form V4 does not know how to authenticate secure connections.

Unless otherwise noted, absolute http://... URLs used in hidden fields can be URLs to any location on the Internet.

If the location is a web page (or "flowto" template) that uses SSI or PHP for part of its content, then an absolute http://... URL should be used. If server location were used instead of URL, then any SSI or PHP content is not inserted and the original SSI/PHP code is left on the page.

Server Location

Because of security considerations, Master Form V4 has some restrictions in place pertaining to where certain files may be "written to" and "read from" when a Server Location is used instead of an Absolute URL. Here is a list of types of files and where they may be located:

Database templates — anywhere on your server.
Email templates — anywhere on your server.
"Thank you" page templates, custom error and banned word/IP page templates, and templates for the second and subsequent pages of multi-page forms —
- In the document root (the directory where your index/home web page is at) or its subdirectories.
- In the cgi-bin (where Master Form V4 is installed) or its subdirectories, so long as the template file name extension is .htm, .html, or .php
The reason for the restrictions is to prevent crackers and spammers constructing their own forms using your installation of Master Form V4 from obtaining a view of documents closer to the server root, which might reveal passwords, email addresses, or other sensitive information that's best kept hidden, and to keep them from viewing scripts and databases in the cgi-bin — this is assuming you have no database file names with any of those three file name extensions.
Database files (any file that Master Form V4 writes or updates) —
- In the document root (the directory where your index/home web page is at) or its subdirectories.
- In the cgi-bin (where Master Form V4 is installed) or its subdirectories.
Because they're easy to exploit, Master Form V4 will not comply with server locations that contain "../" in them. The "../" character sets are removed before determining the directory location

When specifying

an absolute server location for anywhere on your server, or
a location in the document root or subdirectories,

then the location must have a slash as the first character. (Master Form V4 is smart enough to know whether you mean absolute server location or document root location.)

However, when specifying a directory location that is a subdirectory of where Master Form V4 is installed (a location relative to Master Form V4's location), there is no slash as the first character.

An example absolute server location for anywhere on your server:

/username/public_html/subdir/file.txt

Two examples of document root server locations, one with the file in the document root and other with the file in a subdirectory:

/file.txt
/subdir/file.txt

Two examples of directory locations relative to where where Master Form V4 is installed, the first is just a file name, meaning the file is in the same directory as the Master Form V4 files, and the other specifies a file in a subdirectory:

file.txt
subdir/file.txt

Hidden Fields Send Special Instructions

This list of hidden fields, in alphabetical order, describes the special instructions each sends to Master Form V4.

When these hidden field values may have a comma-separated list of field names or file locations, the commas may optionally have white space before and/or after them. White space would be space characters, tab characters, or line feeds.

conditionalattachment

Use the conditionalattachment hidden field to attach a file or files to an outgoing email on demand — when a certain radio button or checkbox(s) are checked, for example.

The ATTACH FileName placeholder (defined elsewhere in this document) is used to always attach certain files to outgoing email. This conditionalattachment hidden field is used to attach certain files only when directed to do so from the form (like a checkbox checked).

The value of the conditionalattachment hidden field is the location of the email template followed by a list of files to attach. Items in the value are separated with a comma and/or space character.

Here is an example with a checkbox:

<input 
   type="checkbox" 
   name="conditionalattachment" 
   value="email.txt, file1.txt, something.html">

email.txt is the location of the email template to be sent with the attachment(s). It must match an email template location specified with the emailtemplate hidden field (defined elsewhere in this document).

Following email.txt is a list of one or more files to attach. These files can be specified in any of several ways:

The absolute URL to the file.
The absolute server location of the file.
The server location of the file relative to the location of the Master Form V4 installation.

Whether radio or checkbox, the field name is always conditionalattachment — if radio, only one can be checked; if checkbox, any or all can be checked.

conditionalrequired

If certain fields become required when a certain selection or choice is made, this hidden field can be used to specify those required fields. For example, if "married" is checked on a form, then information about the spouse might be required.

The format of this hidden field's value is

FieldName,RequiredFieldName

FieldName is the field name of the selection/choice and RequiredFieldName is the required field name.

Example:

<input 
   type="hidden"
   name="conditionalrequired"
   value="artist, medium">

With the above, when the artist field is checked/selected, field medium becomes required.

To make more than one field required, add their field names separated with commas. Example:

<input 
   type="hidden"
   name="conditionalrequired"
   value="married,Mname,Mbirthdate,Mphone">

With the above, when the married field is checked/selected, fields Mname and Mbirthdate and Mphone all become required.

As you can see, the first field name is the conditional field. If it contains a value, then all field names following it become required.

If more than one conditional field must contain a value (be selected/checked) for certain additional fields to become required, the conditional field names are separated with a colon character. Example:

<input 
   type="hidden"
   name="conditionalrequired"
   value="blue:green,grass,water,leaf,sky">

With the above, when both the blue and the green conditional fields have a value (both are checked/selected), then fields grass and water and leaf and sky all become required.

(To have certain fields become required when conditional fields do not have a value, are not selected/checked, use emptyrequired instead of conditionalrequired)

dbfile

This hidden field tells Master Form V4 where the database file is that needs to be updated. The database file can contain information from every form submission, cumulative, or information from each form submission can be in a separate database file.

If a database file doesn't exist, Master Form V4 creates it.

(Note: A database template must also be provided using hidden form field filetemplate so Master Form V4 knows how to construct the database record prior to updating the file.)

The database file location needs to be specified as a Server Location.

More than one database file may be specified with dbfile, along with the same number of file templates with filetemplate. More than one can be specified by separating them with a comma.

Here is an example for two databases:

<input 
   type="hidden" 
   name="dbfile" 
   value="database/file1.csv, 
          database/file2.txt">
<input 
   type="hidden" 
   name="filetemplate" 
   value="templates/csv.txt,templates/tab.txt">

When more than one database is specified, the order of the values lists in name="dbfile" and name="filetemplate" must correspond.

EmailAddressSeparator

When the EMAILS FileName placeholder is used, Master Form V4 extracts any email addresses it finds in file FileName (Read about "placeholders" here.)

The list of email addresses will be separated with the default, a comma/space character pair, unless a different separator is specified with this form field EmailAddressSeparator

Here is an example that specifies a vertical bar character as a separator:

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

To specify a line feed as a separator, use \n and to specify a tab character, use \t

Here is an example that specifies the line feed as a separator to format the list of email addresses one per line.

<input 
   type="hidden" 
   name="EmailAddressSeparator" 
   value="\n">

emailfields

If your form contains any fields for email addresses, list the field names here so Master Form V4 will check that the addresses provided are properly formatted. If you're listing more than one field name, separate the field names with a comma.

The information submitted by the listed form fields are checked for correct format only if the fields contain information. To require the fields to contain information, use hidden form field requiredfields

Here is an example:

<input 
   type="hidden" 
   name="emailfields" 
   value="email,repeatemail">

emailtemplate

When a form is submitted, some or all of the information can be emailed to one or more destinations, the email formatted according to your requirements. The email is custom formatted using an email template.

Hidden field emailtemplate is used to specify the location of the email template.

More than one email can be sent by specifying the locations of more than one email template. When specifying multiple locations, either

put each location into the value of the one hidden field, individual template locations separated with a comma, or
use multiple hidden name="emailtemplate" fields, each specifying a template location.

Example:

<input 
   type="hidden" 
   name="emailtemplate" 
   value="templates/a.txt, 
          templates/b.txt">

Another example:

<input 
   type="hidden" 
   name="emailtemplate" 
   value="templates/a.txt">
<input 
   type="hidden" 
   name="emailtemplate" 
   value="templates/b.txt">

The template file location(s) can be specified as the Absolute URL or Server Location.

Whenever email template locations are specified as the Absolute URL, the domain name in the URL must be the domain name where Master Form V4 is installed. Master Form V4 does not allow email templates to be retrieved by URL from any other location on the Internet as it would open a gaping hole for spammers to take advantage of your installation.

If your template has any email addresses hard coded within it —

It may be prudent to put the template into the cgi-bin somewhere that browsers can't retrieve it. For this to work, a Server Location needs to be used for the name="emailtemplate" value, not an Absolute URL.

If your server allows *.txt files to be loaded into the browser even when the file is located in the cgi-bin, you can rename the email template to .cgi or .pl to cause an Internal Server Error if a spammer's robot tries to read it. (Master Form V4 doesn't care what the file name is so long as it can read it.)

As a workaround, if putting the email template into the cgi-bin is not acceptable or using an Absolute URL is highly desired, then the hidden form field hidden with a secret location that can't be retrieved by browser (see "hidden" entry below) might be used to effectively hide the hidden field containing the Absolute URL. The email template file would still be open to spiders but, so long as the file's URL is not linked from anywhere, they might never find it.

emptyrequired

If certain fields become required when certain other fields are left empty, this hidden field can be used to specify those required fields. For example, if "officer" is unchecked, then information about enlisted status might be required.

The format of this hidden field's value is

FieldName,RequiredFieldName

FieldName is the empty field name and RequiredFieldName is the required field name.

Example:

<input 
   type="hidden"
   name="emptyrequired"
   value="artist, buyer">

With the above, when the artist field is unchecked/unselected/empty, field buyer becomes required.

To make more than one field required, add their field names separated with commas. Example:

<input 
   type="hidden"
   name="emptyrequired"
   value="owner,rentalamount,location,lease">

With the above, when the owner field is blank, fields rentalamount and location and lease all become required.

As you can see, the first field name is the conditional field. If it does not contain a value, then all field names following it become required.

<input 
   type="hidden"
   name="emptyrequired"
   value="red:white,grass,water,leaf,sky">

With the above, when neither red nor white fields have a value, then fields grass and water and leaf and sky all become required.

(To have certain fields become required when conditional fields have a value, or are selected/checked, use conditionalrequired instead of emptyrequired)

errorpage

If you're using a custom web page for presenting Master Form V4 error messages, use this hidden field to tell Master Form V4 where to find it.

The page's location can be specified as the Absolute URL or Server Location.

An Absolute URL to an error page template may be to any location on the Internet. For security reasons, however, if the location is specified as a server location then the error page template must be located in one of these places:

In the document root (the directory where your web pages are) or its subdirectories.
In the cgi-bin (where your scripts are) or its subdirectories, so long as the template file name extension is .htm, .html, or .php

What the above means is that you can put the error page template anywhere in your web page directories. Or, if you want to have it in the cgi-bin, give it one of the three file name extensions.

Example:

<input 
   type="hidden"
   name="errorpage"
   value="templates/error.html">

filetemplate

This hidden field tells Master Form V4 the location of the database template file. The template is used when constructing a record for a database file.

(Note: A database file location must also be provided using hidden form field dbfile so Master Form V4 knows where to create/update the database.)

The template file location can be specified as the Absolute URL or Server Location.

If the template location is specified as the Absolute URL, it can be to any location on the Internet unless the template begins with **OVERWRITE_FILE** (discussed in detail later in this manual). If the template has overwrite instructions, then the template may only be retrieved from the domain where Master Form V4 is installed. The reason for the restriction is to prevent crackers from maliciously overwriting your data files.

More than one file template may be specified with filetemplate and a corresponding number of database file locations with dbfile by separating the lists with a comma.

Here is an example for two databases:

<input 
   type="hidden" 
   name="dbfile" 
   value="database/file1.csv, 
          database/file2.txt">
<input 
   type="hidden" 
   name="filetemplate" 
   value="templates/csv.txt,templates/tab.txt">

When more than one database is specified, the order of the values lists in name="dbfile" and name="filetemplate" must correspond.

flattenfields

When you're having Master Form V4 update a flat file database and you want to include information provided in a textarea form field, the line breaks in the form field must be replaced. That's because a flat file database is one line per record. No line breaks are allowed in any of the record's fields.

List the textarea form field names that will be included in any flat file database. Separate the field names with a comma. Example:

<input 
   type="hidden"
   name="flattenfields"
   value="artist_bio, medium">

The hidden field flattenreplacement may be used to specify what the line breaks will be replaced with. If no replacement is specified, the HTML <br /> tag will be used.

flattenreplacement

When hidden field flattenfields is used to specify textarea form fields to be flattened for a flat file database, line breaks are replaced with the HTML <br /> tag — unless something different is specified with this flattenreplacement hidden field.

This example causes line breaks to be replaced with [LB]

<input 
   type="hidden"
   name="flattenreplacement"
   value="[LB]">

This example causes line breaks to be replaced with the end and begin HTML paragraph tags.

<input 
   type="hidden"
   name="flattenreplacement"
   value="</p><p>">

To replace line breaks with a space, specify a literal space character.

<input 
   type="hidden"
   name="flattenreplacement"
   value=" ">

Use \t to replace line breaks with a tab character.

<input 
   type="hidden"
   name="flattenreplacement"
   value="\t">

Use null (not case sensitive) to remove line breaks altogether (not replaced with anything).

<input 
   type="hidden"
   name="flattenreplacement"
   value="null">

Any ASCII character can be specified with chr(#) where # is the decimal number of the character. This example causes line breaks to be replaced with two consecutive ASCII decimal 16 data link escape characters.

<input 
   type="hidden"
   name="flattenreplacement"
   value="chr(16)chr(16)">

flowto

To personalize/customize the web page displayed after form submission (either the next page of a multi-page form or the "thank you" page), specify the template location with this hidden form field.

If you do not wish to personalize/customize the "thank you" page, consider using hidden field redirect instead. If both hidden fields flowto and redirect are specified in a form, redirect prevails.

The form field flowto can also be used in radio buttons or dropdown lists, instead of a hidden field, when alternate next pages are appropriate.

If Master Form V4 receives more than one flowto URL, it will use only the first one. The order the information is received may vary from form submission to form submission — the browser determines the order the information is sent to Master Form V4 and that is not necessarily the order of the fields presented in the form.

The value of form field flowto can be specified as the Absolute URL or Server Location.

An Absolute URL to a "flowto" page template may be to any location on the Internet. For security reasons, however, if the location is specified as a server location then the "flowto" page template must be located in one of these places:

In the document root (the directory where your web pages are) or its subdirectories.
In the cgi-bin (where your scripts are) or its subdirectories, so long as the template file name extension is .htm, .html, or .php

What the above means is that you can put the "flowto" page anywhere in your web page directories. Or, if you want to have it in the cgi-bin, give it one of the three file name extensions.

Example:

<input 
   type="hidden" 
   name="flowto" 
   value="/hey_thanks.html">

As mentioned, form field flowto can be used in hidden fields and in selection fields.

The flowto value can also be specified in a submit button, but it requires JavaScript and several other details:

Give the form a name, which is specified in the FORM tag. Example:
```
<form name="MyForm" ...
```
The name can be anything you please, so long as the same name is used in the JavaScript (below). In these examples, it's MyForm
Put this hidden field into your form:
```
<input 
   type="hidden" 
   name="flowto" 
   value="">
```
(May be all one line.)

Put this JavaScript somewhere above the form:

<script type="text/javascript">
<!--
function gotoValue(url) {
document.MyForm.flowto.value = url;
}
//-->
</script>

In the above JavaScript, change MyForm to whatever your form's name is.

The submit button tag needs to have this JavaScript within it:
```
onClick="gotoValue('/page.html');"
```
(Replace /page.html with the location of the template page, either the Absolute URL or Server Location.)

Here is an example submit button:
```
<input 
   type="submit" 
   onClick="gotoValue('/page.html');" 
   value="Click Me">
```
(May be all one line.)

hidden

Any other hidden fields may be removed from the form and put into a separate file on the server. Then, use hidden field hidden to tell Master Form V4 where to find the file.

Example:

<input 
   type="hidden" 
   name="hidden" 
   value="data/myfile.txt">

(May be all one line.)

myfile.txt (or whatever you decide to name the file) contains one or more hidden fields, formatted just like they would be if you copied and pasted them from the source code of your form.

The hidden fields in that external file can be more than hidden, they can be secret. No amount of viewing the source code of your web page form will reveal them.

The myfile.txt can be in the cgi-bin to prevent snooping. If your server allows browsers to read .txt files in the cgi-bin, the file might be named myfile.cgi — the file name itself doesn't matter to Master Form V4.

JSfields

When writing a file (a database in Master Form V4 parlance) to be syndicated with JavaScript to various web pages or even other web sites, the form information needs to be converted to JavaScript document.write() commands.

Use this hidden field to tell Master Form V4 which form field values shall be converted to JavaScript document.write() commands when the values are written to a file. When specifying more than one form field name, separate them with a comma.

Here is an example of how it works.

Let's assume the hidden field looks like this:

<input 
   type="hidden"
   name="JSfields"
   value="name, comment">

Let's further assume the database template contained:

document.write('<p><b>');
[[name]]
document.write('</b></p>');
document.write('<p>');
[[comment]]
document.write('</p>');

Now, let's suppose the form user typed Joe Billy as his name and I'm good for it! as the comment.

The database file, then, would be printed as:

document.write('<p><b>');
document.write('Joe Billy');
document.write('</b></p>');
document.write('<p>');
document.write('I\'m good for it!');
document.write('</p>');

That file can then be syndicated in web pages by using the file's URL in a JavaScript tag (assuming the file is in a public document area). Example:

<script
    type="text/javascript"
    language="JavaScript"
    src="http://example.com/databasefile.js">
</script>

Textarea form fields are handled in a special way when being converted to JavaScript document.write() commands.

If the textarea field value contains line feeds, then each line is converted to a JavaScript document.write() command. For example, this:

Hello
I'm here, too.

would be converted to

document.write('Hello');
document.write('I\'m here, too.');

The exception would be when hidden field flattenfields is used to specify the textarea value to be all one line. In that case, the form field value would be converted to this JavaScript command (assuming the default line break replacement):

document.write('Hello<br />I\'m here, too.');

If you want the web page to cause a line break in the text wherever the user typed a line break in the form, use hidden field flattenfields to cause <br /> to be inserted into the JavaScript at the appropriate places. This may be contrary to instinct, but is the way to cause the <br /> tag to be printed instead of just a line feed. (Line feeds in HTML web pages do not cause a corresponding line break in the text. <br /> or some other HTML tag needs to be used — which hidden field flattenfields provides.)

nocarry

When processing multi-page forms (see Multi-page Forms), the [[INSERT_HIDDEN_FIELDS]] placeholder is used to automatically carry form fields from one form page to the next. With that placeholder, all form fields are carried over — except fields listed in this hidden field nocarry

Use the hidden field nocarry to list the form field names that should not be carried over to the next form page. Often, nocarry itself needs to be listed.

When listing several field names, separate them with commas.

Example:

<input 
   type="hidden" 
   name="nocarry" 
   value="flowto, 
          nocarry,
          emailfields,
          requiredfields">

redirect

To send the user's browser directly to a specific URL after the form is submitted (the "thank you" page), without customization/personalization, specify the URL with this hidden form field.

The page's URL needs to be specified as the Absolute URL or a URL relative to the URL of where Master Form V4 is installed. Example:

<input 
   type="hidden" 
   name="redirect" 
   value="http://example.com/hey_thanks.html">

(This is the only form field on this "hidden fields" list that may contain a relative http://... URL to specify the location of a page. This is because the page is not retrieved and processed as a template; instead, the user's browser is redirected straight to the URL.)

If you want to present a personalized/customized "thank you" page, use hidden field flowto instead.

If both hidden fields redirect and flowto are specified in a form, redirect prevails.

paragraphize

To put the content of a form field or fields into paragraph <p></p> tags on the web page that is to be displayed next (the web page specified with the flowto hidden field), specify the field names with this hidden form field.

Separate multiple field names with commas.

Example:

<input 
   type="hidden" 
   name="paragraphize" 
   value="message, addendum">

requiredfields

If your form contains any fields that must be filled in before the form can be submitted successfully, list the field names here. If you're listing more than one field name, separate the names with a comma.

Example:

<input 
   type="hidden" 
   name="requiredfields" 
   value="name, email">

selectionmaximum

If you have checkboxes and/or selection menus on your form, and you require that the user makes no more than a specific maximum number of choices, this field can be used to specify that maximum. The format is

FieldName:#

Where FieldName is the field name and # is the maximum number that may be chosen.

Example:

<input 
   type="hidden"
   name="selectionmaximum"
   value="colors:4">

The above specifies that no more than 4 choices may be made from the "colors" field.

Sometimes, more than one field name has it's own maximum. When specifying the individual maximums, either

put each form field maximum into the value of the one hidden field, specifications separated with a comma, or
use multiple hidden fields, each specifying a form field maximum.

Here is an example of two form field maximums specified in one hidden field:

<input 
   type="hidden"
   name="selectionmaximum"
   value="colors:10,shapes:1">

The above specifies that no more than 10 choices may be made from the "colors" field and no more than 1 choice from the "shapes" field.

Here is an example of two form field maximums, each maximum specified in its own hidden field:

<input 
   type="hidden"
   name="selectionmaximum"
   value="colors:10">
<input 
   type="hidden"
   name="selectionmaximum"
   value="shapes:1">

The above two hidden fields specify that no more than 10 choices may be made from the "colors" field and no more than 1 choice from the "shapes" field.

selectionmaximum can do even more.

If you require a maximum number of choices totalled together from several form fields, it can be done. Here is the format:

FNone:FNtwo:FNthree:#

The field names with choices to be totalled together are listed separated with colon characters, followed by another colon character and the maximum number. Here is an example:

<input 
   type="hidden"
   name="selectionmaximum"
   value="colors:shapes:sizes:9">

The above specifies that no more than 9 choices may be made among field names "colors", "shapes", and "sizes".

To specify an exact number of choices required, use both hidden field selectionmaximum and hidden field selectionminimum

Example:

<input 
   type="hidden"
   name="selectionmaximum"
   value="shapes:3">
<input 
   type="hidden"
   name="selectionminimum"
   value="shapes:3">

The above requires exactly three choices from field "shapes".

selectionminimum

If you have checkboxes and/or selection menus on your form, and you require that the user makes a minimum number of choices, this field can be used to specify that minimum. The format is

FieldName:#

Where FieldName is the field name and # is the minimum number that must be chosen.

Example:

<input 
   type="hidden"
   name="selectionminimum"
   value="colors:4">

The above specifies that at least 4 choices must be made from the "colors" field.

Sometimes, more than one field name has it's own minimum. When specifying the individual minimums, either

put each form field minimum into the value of the one hidden field, specifications separated with a comma, or
use multiple hidden fields, each specifying a form field minimum.

Here is an example of two form field minimums specified in one hidden field:

<input 
   type="hidden"
   name="selectionminimum"
   value="colors:10,shapes:1">

The above specifies that at least 10 choices must be made from the "colors" field and at least 1 choice from the "shapes" field.

Here is an example of two form field minimums, each minimum specified in its own hidden field:

<input 
   type="hidden"
   name="selectionminimum"
   value="colors:10">
<input 
   type="hidden"
   name="selectionminimum"
   value="shapes:1">

The above two hidden fields specify that at least 10 choices must be made from the "colors" field and at least 1 choice from the "shapes" field.

selectionminimum can do even more.

If you require a minimum number of choices totalled together from several form fields, it can be done. Here is the format:

FNone:FNtwo:FNthree:#

The field names with choices to be totalled together are listed separated with colon characters, followed by another colon character and the minimum number. Here is an example:

<input 
   type="hidden"
   name="selectionminimum"
   value="colors:shapes:sizes:9">

The above specifies that a total of 9 choices must be made among field names "colors", "shapes", and "sizes".

To specify an exact number of choices required, use both hidden field selectionminimum and hidden field selectionmaximum

Example:

<input 
   type="hidden"
   name="selectionminimum"
   value="shapes:3">
<input 
   type="hidden"
   name="selectionmaximum"
   value="shapes:3">

The above requires exactly three choices from field "shapes".

submitget

This hidden field submitget and the related hidden field submitpost can be used to submit form information to other form handling scripts located on the Internet. Use submitget for method="GET" submissions and submitpost for method="POST" submissions.

The value of the hidden field is the Absolute URL of the form handling script (which can be anywhere on the Internet) and a list of field names to be submitted to the URL. The URL and field names are separated with commas.

Example:

<input 
   type="hidden" 
   name="submitget" 
   value="http://example.com/cgi-bin/ezine.cgi,
          name,
          email">

Failure to submit the information (destination software errors out or is unreachable, for examples) does not interrupt the rest of Master Form V4's data processing. On recognized failure, an email notice is sent to the "Problem Alerts" email address — if an address has been specified at the "Email Configuration" control panel page.

submitpost

This hidden field submitpost and the related hidden field submitget can be used to submit form information to other form handling scripts located on the Internet. Use submitpost for method="POST" submissions and submitget for method="GET" submissions.

Example:

<input 
   type="hidden" 
   name="submitpost" 
   value="http://example.com/cgi-bin/ezine.cgi,
          name,
          email">

uploadedfilesaveinfo

When your form allows file uploads and you want to save uploaded files on your server, use this hidden field to specify the location of a template containing information Master Form V4 will use to determine where the uploaded files will be saved.

The page's location can be specified as the Absolute URL or Server Location. Example:

<input 
   type="hidden"
   name="uploadedfilesaveinfo"
   value="templates/uploadstorageinfo.txt">

Whenever uploadedfilesaveinfo template locations are specified as the Absolute URL, the domain name in the URL must be the domain name where Master Form V4 is installed. This is to prevent malicious overwriting of your server files

See Saving Uploaded Files On The Server for information about creating the template file that hidden field uploadedfilesaveinfo specifies.

use_numbering_key

This hidden field use_numbering_key is used to cause sequential numbering of form submissions. The hidden field value is an id under which submission counts are incremented.

The sequential numbering id is independent of form name or location. The same key may be used in more than one form. And an individual form may use one key for one submission and a different key for the next.

The Master Form V4 control panel has a link to a page where all current sequential numbering keys and their latest incremented number can be viewed.

The hidden field use_numbering_start may be used to start the numbering. Without it, number defaults to starting with the digit 1.

Numbering is not restricted to only numbers. When non-numbers are present, the last set of digits is incremented. If no digits are present, a digit is appended.

Here is how incrementation takes place with different sequential numbers:

If the previous or start number is this,	then the incremented number becomes this.
23	24
w23	w24
23w	24w
w23w	w24w
23w23	23w24
23w23w	23w24w
23w23w23	23w23w24
w	w1
[blank]	1
ID # XAC-23	ID # XAC-24

Example of use:

<input 
   type="hidden"
   name="use_numbering_key"
   value="Affiliate Leads">

Placeholder [[use_number]] can be used to insert the sequential number into email, web page, and database templates.

use_numbering_start

This hidden field use_numbering_start is used to specify the first recording of a sequential numbering of form submissions. Once number has started, this field no longer has an effect.

The hidden field use_numbering_key is used to specify the key or id under which numbering is incremented.

Example of use:

<input 
   type="hidden"
   name="use_numbering_start"
   value="AL-1">

Placeholder [[use_number]] can be used to insert the sequential number into email, web page, and database templates.

NOTE:
Hidden fields in addition to the above are allowed. Your needs may require one or more hidden fields for use in outgoing emails, recording in a database, or inserting into a personalized page

Example:
You may have several forms that all use the same email template, and you want the subject of the email to depend on which form was used. In this case, you might have

<input
    type="hidden"
    name="subject"
    value="This form's subject">

in your forms. And, in your email template, you use the subject placeholder in the email header like this:

Subject: [[subject]]

This method would allow you to maintain only one email template. Yet, you can use it for several different forms, with each form providing it's own unique email subject line.

Placeholders
Conditional Placeholder Sets
Special Placeholders

Creating Templates

Master Form V4 uses templates to format any web page, email, or database record you wish to use in the task you have set up for the software to perform.

You design each template to look as you wish and then add placeholders wherever you want Master Form V4 to insert live data.

Placeholders

Placeholders can be any form field name, including hidden field names if you wish. In addition, special placeholders can be used for current date, current time, custom error message, self/user identifying information, and uploaded file handling.

Placeholders are case sensitive.

Placeholder names are enclosed in double square brackets or in an HTML comment tag. Here is an example of each:

[[placeholder]]
<!--placeholder-->

If your form had a field named "firstname" and your personalized "thank you" page template had

<p>Thank you, [[firstname]], for ...
<p>Thank you, <!--firstname-->, for ...

then, if the user typed "William" into the form field, Master Form V4 would generate the "thank you" page as

<p>Thank you, William, for ...
<p>Thank you, William, for ...

If no data is available for a placeholder, what happens depends on what encloses the placeholder. If the placeholder is in double square brackets, it is removed. If the placeholder is in an HTML comment tag, is is left as is.

Note: If you need to have double square brackets in your web page, email, or database record, specify them as [-[ and ]-]. Master Form V4 will replace those two sets with [[ and ]], respectively. For example,

[-[my special double square bracket text]-]

will be replaced with

[[my special double square bracket text]]

Conditional Placeholder Sets

You can also specify conditional placeholder sets. A conditional placeholder set prints content only if information is available for the placeholder name itself. The format for a conditional placeholder set is either of these:

[[if_placeholder]] content [[/if_placeholder]]
<!--if_placeholder--> content <!--/if_placeholder-->

The first placeholder of the set begins with if_ followed by the placeholder name. The last placeholder of the set begins with /if_ followed by the placeholder name. Given:

[[if_firstname]]Name: [[firstname]][[/if_firstname]]
<!--if_firstname-->Name: <!--firstname--><!--/if_firstname-->

then, if the user typed "William" into the form field named "firstname", Master Form V4 would print

Name: William
Name: William

but if no information is available for the placeholder name itself then nothing between the placeholder set is printed.

Another conditional placeholder you can specify is theifnot_ set. This conditional placeholder set prints content only if information is not available for the placeholder name itself. The format is either of these:

[[ifnot_placeholder]] content [[/ifnot_placeholder]]
<!--ifnot_placeholder--> content <!--/ifnot_placeholder-->

The first placeholder of the set begins with ifnot_ followed by the placeholder name. The last placeholder of the set begins with /ifnot_ followed by the placeholder name. Given either:

Name: [[ifnot_firstname]]Anonymous[[/ifnot_firstname]]
Name: <!--ifnot_firstname-->Anonymous<!--/ifnot_firstname-->

then, if the user left the form field named "firstname" blank, Master Form V4 would print

Name: Anonymous
Name: Anonymous

but if any information is available for the placeholder name itself then nothing between the placeholder set is printed. In other words, if nothing is available, Anonymous is printed, but if something is available, nothing is printed.

Here is an example of using both the if_ and ifnot_ conditional placeholder sets to control what is printed:

<p>
Your record will show this name: 
<!--if_firstname--><!--firstname--><!--/if_firstname-->
<!--ifnot_firstname-->Anonymous<!--/ifnot_firstname-->
</p>

In the above example, if the user typed "William" into the form field named "firstname", Master Form V4 would print

<p>
Your record will show this name: 
William

</p>

Otherwise, it would print

<p>
Your record will show this name: 

Anonymous
</p>

Formatting Note

The extraneous blank lines won't display in browsers. But if you are sending a plain text email or creating a plain text file, the blank lines probably would not be acceptable.

To correct, include the linefeed characters between the conditional placeholders. That way, one will print but not both. Example:

Your record will show this name:[[if_firstname]]
   [[firstname]][[/if_firstname]][[ifnot_firstname]]
   Anonymous[[/ifnot_firstname]]

In that example, if the user typed "William" into the form field named "firstname", Master Form V4 would print

Your record will show this name: 
   William

Otherwise, it would print

Your record will show this name: 
   Anonymous

To avoid all linefeed characters in a plain text file, put all placeholders on one line.

Special Placeholders

This is a list of the special placeholders and the information available to them:

Special placeholders related to

Current date
Current time
Email header date/time
Custom error message
Multi-page form
Self/User identification
Separating values
Inserting email addresses extracted from a file
Email content insertion and file attachment
Form user uploaded file handling
Counting and mathematical operations

For each Placeholder Name, format as either —

[[placeholder]]
or

Current date related placeholders
(the date on the server where Master Form V4 is being used) —

DAY

This prints today's day of the month. If this were the second day of the month, a "2" would be printed.

DAY2

This prints today's day of the month. If the day is a single digit, a zero is prepended to make it two digits. The second day of the month is printed "02".

LONGMONTH

The name of today's month, spelled out. The month of June is printed "June" (assuming English month names are used).

MONTH

This is the number of today's month. January is printed as "1" and December is printed as "12".

MONTH2

This is the number of today's month. If the month number is a single digit, a zero is prepended. January is printed as "01" and December is printed as "12".

SHORTMONTH

The name of today's month, abbreviated. The month of June is printed "Jun" (assuming standard 3-letter English month abbreviations are used).

SYSTEMTIME

This is a number representing the number of seconds elapsed since January 1, 1970 at the moment the Master Form V4 program is called upon to process a form submission. This is a 10-digit number.

WEEKDAY

Today's day of the week. Monday is printed as "Monday", (assuming English weekday names are used) .

YEAR

This is today's year number (four digits). Year 2007 is printed as "2007".

YEAR2

This is today's year number reduced to two digits. Year 2007 is printed as "07".

Current time related placeholders

(the time on the server where Master Form V4 is being used) —

AMPM

If the current time is before noon, "AM" is printed; otherwise, "PM" is printed.

AMPMHOUR

The hour number of the current time using a 12-hour clock. The sixth hour is printed as "6".

AMPMHOUR2

The hour number of the current time using a 12-hour clock. If the hour number is a single digit, a zero is prepended. The sixth hour is printed as "06".

HOUR

The hour number of the current time using a 24-hour clock. The sixth hour is printed as "6".

HOUR2

The hour number of the current time using a 24-hour clock. If the hour number is a single digit, a zero is prepended. The sixth hour is printed as "06".

MINUTE

The minute number of the current time. The sixth minute after the hour is printed as "6".

MINUTE2

The minute number of the current time. If the minute number is a single digit, a zero is prepended. The sixth minute after the hour is printed as "06".

SECOND

The second number of the current time. The sixth second after the minute is printed as "6".

SECOND2

The second number of the current time. If the second number is a single digit, a zero is prepended. The sixth second after the minute is printed as "06".

SYSTEMTIME

This is a number representing the number of seconds elapsed since January 1, 1970 at the moment the Master Form V4 program is called upon to process a form submission. This is a 10-digit number.

Email header formatted date/time placeholder —

HEADER_TIME_STAMP

This will print the current date and time on the server, converted to Greenwich Mean Time, in a format appropriate for inclusion in email header lines. Here is an example of such a time stamp:

Tue, 5 Feb 2013 14:58:48 -0000

Although this date/time stamp will be printed anywhere by using the placeholder in templates, it was created for specifying a "Received:" email header line for tracking documentation in case of spamming complaints.

To specify a "Received:" email header line, insert this into your email template in the header lines area at the top of the file, modified according to the instructions that follow.

Received: from [[__(A)__]]
  (not verified [[[IP]]]) by [[SELFDOMAIN]] for 
  <[[__(B)__]]>; [[HEADER_TIME_STAMP]]

Instructions:

The above three lines need to be all one line in the email template. It's presented here in multiple lines because of user's manual text column width considerations.
Replace __(A)__ with the form field name containing the form user's email address, which would be considered to be the sender's email address.
The triple square brackets around the IP placeholder is intentional. When placeholder IP is replaced with the IP address of the form user, one set of square brackets will remain, which is what we want. Example: [123.456.7.89]
Replace __(B)__ with the form field name containing the address where the email is being sent to, which would be considered to be the destination address. (Note that __(A)__ and __(B)__ may be the same address.)

Once those changes are made, you might have something like this (again, it must be all one line in your email template):

Received: from [[sender]]
  (not verified [[[IP]]]) by [[SELFDOMAIN]] for 
  <[[destination]]>; [[HEADER_TIME_STAMP]]

When you receive a test email created from a template with a "Received:" line constructed according to the above, view the email with full headers. You'll see something like this:

Received: from sender@example.com
  (not verified [123.456.7.89]) by example.com for
  <receiver@example.com>; Tue, 5 Feb 2013 14:58:48 -0000

Spamming accusation vulnerability is especially high when the form user can fill in an email address where an acknowledgment is automatically sent — and the acknowledgment email includes information provided by the form user.

A "Received:" line like this with the user's IP address can allow automated email backtracking software to find the form user's IP address as the source (instead of you being the source). It won't fool all automated systems, and may never fool manual examination of the email headers. But at least the IP address of the form user, is recorded and available to the examiners.

Email addresses can be spoofed, of course, but those aren't necessary when a good IP address is present. There are services that allow folks to surf anonymously, which cloaks their real IP address in lieu of the IP address of the cloaking service — which may present a dead end to investigators, but at least it doesn't dead end at your server.

Be aware that adding an extra "Received:" line with an IP address pointing to a different server is a common spammer practice to deflect suspicion. Using the extra "Received:" line for the reason stated above, however, is using it to point to the real culprit rather than to hide nefarious activities of your own.

To avoid this vulnerability, just don't include any information submitted with the form when an email is sent to an address specified on the form.

Custom error message related placeholder —

ERROR_MESSAGE

When a custom error message page is used, this placeholder is replaced with the error message composed by Master Form V4. (See Custom Error Page.)

Multi-page form related placeholder —

INSERT_HIDDEN_FIELDS

When multi-page forms are used, this placeholder is used in the second and subsequent form pages. The placeholder is put between the <FORM...>and </FORM>tags. The placeholder is then replaced with hidden fields containing values carried over from previous pages of the multi-page form. (See Multi-page Forms.)

Self/User identification related placeholders —

ALLME

This is the file name of the Master Form V4 program being called upon to process a form submission. If available via the script's environment variables, the server directory path to the file's location is included.

This is the IP address of the form user.

This is the file name of the Master Form V4 program being called upon to process a form submission.

REFERRER

This is the URL of the form that was used, provided the browser sends that information to Master Form V4 when the form is submitted. Browser privacy settings or personal firewall software on the user's computer might prevent the browser from providing the referring URL.

SCRIPT_LOCATION

This is the location and name of the script being used to process the form. It can be especially useful when used in the header of the outgoing email with an X-...: header name, such as X-Script-Location:. (Custom email header lines can be created when they begin with X-...: and contains no spaces. Most email programs have a way to reveal full headers, which would reveal custom headers.) Here is an example of a custom header line with this placeholder:
X-Script-Location: [[SCRIPT_LOCATION]]

SELFDOMAIN

This is the domain name where the script is running. Actually, it is the value of the "SERVER_NAME" environment variable. The environment variable might be an IP address but is usually the domain name, with or without the leading "www."

Special placeholder for separating values —

FieldName SeparateWith()

When a field name has more than one value, this placeholder can used to indicate how the values shall be separated when they are printed in the placeholder's place.

When using the normal [[FieldName]] placeholder and the field name has more than one value, the values are separated with a tab character. To separate with something other than a tab character, the [[FieldName SeparateWith(_____)]] placeholder is used.

This special placeholder has three parts:

Part Description
FieldName This is the field name that has or might have more than one value.

SeparateWith This is the directive Master Form V4 looks for when determining whether or not your template has any of these special placeholders.

(_____) This is an open parenthesis character, whatever you want the values separated with, and a close parenthesis character. What you put between the parenthesis is up to you. It can include line breaks, HTML code, tab characters, whatever you need the values separated with. (This is the only placeholder that can include line breaks.) If you don't want the values separated with anything, put nothing between the parenthesis.

Part	Description
FieldName	This is the field name that has or might have more than one value.
SeparateWith	This is the directive Master Form V4 looks for when determining whether or not your template has any of these special placeholders.
(_____)	This is an open parenthesis character, whatever you want the values separated with, and a close parenthesis character. What you put between the parenthesis is up to you. It can include line breaks, HTML code, tab characters, whatever you need the values separated with. (This is the only placeholder that can include line breaks.) If you don't want the values separated with anything, put nothing between the parenthesis.

Here is an example. Let's suppose your form field name="colors" has three values, "red", "blue", and "pink". And let's suppose you have the following in your plain text email template:

Colors checked
     >> [[colors SeparateWith(
     ~~ )]]

The above will be replaced with a line break, five spaces, two tildes, and another space. It will be printed as:

Colors checked
     >> red
     ~~ blue
     ~~ pink

Checkboxes and list boxes are natural candidates for this placeholder. However, it can also be used in other ways.

For example, if you have a form that asks for the user's postal mailing address, you might have two or three fields for the "street" address. Example:

Name:
   <input type="text" name="yourname">
Address line 1:
   <input type="text" name="address">
Address line 2:
   <input type="text" name="address">
Address line 3:
   <input type="text" name="address">
City:
   <input type="text" name="city">

Now, these placeholders:

Name:    [[yourname]]
Address: [[address SeparateWith(
         )]]
City:    [[city]]

will print (making assumptions about what the user filled in):

Name:    Will
Address: RR 1
         Box 274
City:    Greenly Village

The special SeparateWith directive prints only values that are available. In the above example, it was assumed the user used only two of the available name="address" fields.

Inserting email addresses extracted from a file —

EMAILS FileName

This placeholder will be replaced with a list of email addresses found in the file specified as FileName. The file may contain other information. Master Form V4 will extract only the email addresses.

The list of email addresses will be separated with a comma/space character pair unless a different separator is specified with form field EmailAddressSeparator

If the file is not in the directory where Master Form V4 is installed, the directory must be specified with the file name.

As an example of use, let's suppose you have a small list of business associates' email addresses in a file and that you want to send them all a copy of an email that's sent when a certain form is submitted.

You might have a Bcc: email header line in your template something like this:

Bcc: [[EMAILS data/emails.txt]]

The above placeholder would be replaced with a list of all email addresses found in file data/emails.txt. The Bcc: line has a limit depending on how many email addresses or how much information the server's mailer (sendmail or qmail) will allow on that header line. The limit may be several dozen or a thousand or more.

If several files of email addresses need to be extracted for one set of emails, use an EMAILS FileName placeholder for each. Example:

[[EMAILS emails1.txt]], [[EMAILS emails2.txt]]

Notice the comma and space between the two placeholders. If you're using a different separator character or characters for the extracted email addresses, the same should be between the two EMAILS placeholders for a seamless merge.

This is a powerful placeholder. Master Form V4 can extract email addresses from any plain text file, which might be an email folder file such as the kind Eudora or Thunderbird maintain, or it might be an ezine subscription list that you keep up-to-date.

The extracted email addresses can be put into email Bcc lines, as indicated above. Or, they can be sent to yourself in the body of an email, and/or stored in a plain text file on the server (the latter using a file template instead of an email template).

Email content insertion and file attachment placeholders —

INSERT FileName

This placeholder inserts the indicated file (the file being on the server or on the Internet) into the place where the placeholder is found.

Replace FileName with the location and name of the file to be inserted. FileName can be any one of:

The absolute URL to the file.
The absolute server location of the file.
The server location of the file relative to the location of the Master Form V4 installation.

Here are a few examples:

[[INSERT /www/example/htdocs/file.txt]]
[[INSERT /file.txt]]
[[INSERT databases/file.csv]]
[[INSERT http://example.com/page.html]]

To send a web page in an email, use email headers for HTML email (see Email Templates) and an INSERT FileName tag for the body content. Master Form V4 will retrieve the web page and insert it into the email.

ATTACH FileName

This placeholder attaches the indicated file (the file being on the server or on the Internet) to the email generated with the template where the placeholder is found.

Replace FileName with the location and name of the file to be attached. FileName can be any one of:

The absolute URL to the file.
The absolute server location of the file.
The server location of the file relative to the location of the Master Form V4 installation.

Here are a few examples:

[[ATTACH /www/example/htdocs/file.txt]]
[[ATTACH /file.txt]]
[[ATTACH databases/file.csv]]
[[ATTACH http://example.com/page.html]]

To attach a web page to an email, use an ATTACH FileName tag somewhere in the body content. Master Form V4 will retrieve the web page and attach it.

Form user uploaded file handling placeholder —

FieldName UPLOAD ...

This placeholder is multi-part. The FieldName and UPLOAD parts are required. The ... part is optional and may be replaced by one or more of the following:

ONLY: _____
NEVER: _____
MAXSIZE: _____
DIRECTORY: _____

The Email Templates and Saving Uploaded Files On The Server sections contain examples using the file upload placeholder.

Each part is addressed here:

FieldName

The form field where the user specifies the file to be uploaded has a field name. Replace FieldName with that form field name.

Here is an example that assumes the form field name is "afile":
```
[[afile UPLOAD]]
```
FieldName and UPLOAD are the only two required parts.
UPLOAD

The placeholder must contain the word UPLOAD — here is an example:
```
[[afile UPLOAD]]
```
UPLOAD is required so Master Form V4 knows the placeholder relates to an uploaded file.
ONLY: _____

If you use this part, you're telling Master Form V4 what type of files are the only ones that may be uploaded. Replace the underline with a list of allowed file name extensions (with or without the period/dot). If you list two or more file name extensions, separate them with a comma and/or a space. Example:
```
[[afile UPLOAD ONLY: .gif, .jpg,jpeg png]]
```
To specify files with no extension, use a period/dot character by itself.

If both the ONLY: _____ and NEVER: _____ parts are used, then NEVER: _____ takes precedence.
NEVER: _____

If you use this part, you're telling Master Form V4 what type of files may never be uploaded. Replace the underline with a list of disallowed file name extensions (with or without the period/dot). If you list two or more file name extensions, separate them with a comma and/or a space. Example:
```
[[afile UPLOAD NEVER: exe .src]]
```
To specify files with no extension, use a period/dot character by itself.

If both the ONLY: _____ and NEVER: _____ parts are used, then NEVER: _____ takes precedence.
MAXSIZE: _____

If you use this part, replace the underline with a number representing the maximum file size that may be uploaded, optionally with a block size character. If no block size character is provided, b for "byte" is assumed.

Here is a list of block size characters along with the name and block size each represents:
```
b byte     1 byte
k kilobyte 1,024 bytes
m megabyte 1,048,576 bytes
g gigabyte 1,073,741,824 bytes
t terabyte 1,099,511,627,776 bytes
p petabyte 1,125,899,906,842,624 bytes
e exabyte  1,152,921,504,606,846,976 bytes
```
Here is an example that specifies two and one-half megabytes as the maximum file size that may be uploaded:
```
[[afile UPLOAD MAXSIZE: 2.5m]]
```
It is unlikely that a block size larger than m will be needed. But if it is, Master Form V4 can handle the number — provided the server has sufficient resources.
DIRECTORY: _____

This part is optional and applies only to files that will be stored on the server.

If you use this part, replace the underline with the directory location where you want the uploaded file saved to.

If the DIRECTORY: _____ part is not used, it is assumed the directory where the file should be saved is the same directory where Master Form V4 is installed.

Here is an example that saves the uploaded file one directory down from where Master Form V4 is installed, in subdirectory "uploads".
```
[[afile UPLOAD DIRECTORY: /uploads]]
```
The DIRECTORY: _____ part is used only to specify the directory where uploaded files are to be saved. The saved file name will be the same as the file name that was uploaded — unless that would overwrite an existing file, in which case the file name is adjusted with a digit. For example, if file mypic.gif was uploaded and a mypic.gif already existed in the directory where the file is to be saved, then the newly uploaded file would be named mypic2.gif

Counting and mathematical operations placeholders —

COUNT FieldName

This placeholder is replaced with the number of values the FieldName contains. FieldName is the name of the form field with values to be counted.

Let's suppose you had a series of checkboxes, each name="colors" and the user checks off five colors. Then this placeholder:

[[COUNT colors]]

would be replaced with the number 5

Checkboxes and list boxes are natural candidates for the COUNT FieldName placeholder. However, it can also be used in other ways.

For example, if you have a form that asks for the user's postal mailing address, you might have two or three fields for the "street" address. Example:

Address line 1:
   <input type="text" name="address">
Address line 2:
   <input type="text" name="address">
Address line 3:
   <input type="text" name="address">

Now, this placeholder:

[[COUNT address]]

will report how many lines the user filled in.

The COUNT FieldName placeholder can also be used within the MATH placeholder to do calculations with. See below.

MATH operation
MATH# operation

This placeholder is replaced with the result of the mathematical operation specified in operation. The operation would normally include one or more field names with numbers for values.

Here are several example placeholders, one operating an addition and one a division:

[[MATH Item1 + Item2]]
[[MATH Item1 / Item2]]

Assuming form field name Item1 has a value of 33 and field name Item2 has a value of 7, then those two placeholders will be replaced with:

40
4.71428571428571

Note that division accuracy is limited by the number of decimal places your installation of Perl can utilize when doing calculations.

If MATH is followed by a number, the result will be rounded to the number of decimal places indicated. (Rounding is to the nearest number. For two decimal places 1.001 would be rounded to 1.00 and 1.005 would rounded to 1.01.)

Here are the same examples except with two decimal places:

[[MATH2 Item1 + Item2]]
[[MATH2 Item1 / Item2]]

Assuming the field names have the same values as before, those placeholders would be replaced with:

40.00
4.71

Rounding to the nearest whole number can be had by specifying MATH0 (that's a digit 0, not an alphabetical letter O).

[[MATH0 Item1 + Item2]]
[[MATH0 Item1 / Item2]]

Assuming the field names have the same values as before, those placeholders would be replaced with:

40
5

Note that rounding accuracy is limited by the number of decimal places your installation of Perl can utilize when doing calculations.

The following mathematical symbols may be used in operation:

Symbol	Operation
+	addition
-	subtraction
/	division
%	remainder
r	remainder
R	remainder

Symbol	Operation
*	multiplication
x	multiplication
X	multiplication
**	exponentiation
xx	exponentiation
XX	exponentiation

The operation may include parenthesis to force calculation of certain parts of the equation before other parts. The part between the parenthesis will be calculated first.

Here are two examples:

[[MATH (Item1 / Item2) + Item2]]
[[MATH Item1 / (Item2 + Item2)]]

Assuming form field name Item1 has a value of 33 and field name Item2 has a value of 7, then those two placeholders will be replaced with:

11.7142857142857
2.35714285714286

In the first placeholder, 33 is divided by 7, then 7 is added. In the second placeholder 7 is added to 7, resulting in 14, then 33 is divided by 14 .

Numbers can be included in the operation in addition to or instead of form field names. Here are several examples:

[[MATH ((Item1 / Item2) + Item2) - 9]]
[[MATH 44 / (2 + 4)]]
[[MATH Item1 * Item2]]
[[MATH Item1 / Item2]]
[[MATH Item1 % Item2]]

Assuming the values of the form fields are as before, the above placeholders would be replaced with:

2.71428571428572
7.33333333333333
231
4.71428571428571
5

The COUNT placeholder may be used in conjunction with the MATH and MATH# placeholders. Simply put the COUNT placeholder where you would otherwise have a form field name. Use the entire COUNT placeholder, including its double square brackets.

As an example of use, let's suppose you sold certain types of documents at $1.25 each. Your order form lists the documents next to checkboxes customers can check to buy. Form field names of the checkboxes are name="documents".

On the "thank you" page, you wish to present the total amount of the order, including an order tax of 6.5%.

In the example below, I've presented some of the MATH# placeholders as multiple lines. This is to assist visual understanding. In practice, MATH# and MATH placeholders need to be all one line.

<p>
Number of documents: 
[[COUNT documents]]
</p>
<p>
Cost of documents: 
[[MATH2 [[COUNT documents]] * 1.25]]
</p>
<p>
Tax on documents: 
[[MATH2 
   ([[COUNT documents]] * 1.25) 
                        * 0.065]]
</p>
<p>
Total cost: 
[[MATH2 
   (
    ([[COUNT documents]] * 1.25) 
                         * 0.065) + 
         [[COUNT documents]] * 1.25]]
</p>

Email Templates

To generate an email, Master Form V4 reads an email template file and replaces any placeholders it finds in the template. Once generated, the email is sent.

An email template file is a plain text file containing the entire email, including the email headers. The template file may contain placeholders. See Creating Templates, above.

Master Form V4 is told where to find the email template file by a hidden field in the form named emailtemplate. If you don't want the form submission to generate an email, just omit the hidden field.

Using the email template, you can format the emails the way you want to receive them (or have them sent), with the data you want to see arranged in the way you want it.

An email template file must contain an email header. The email header may contain many things, but it must contain at least a To line.

Email body content isn't actually required, but usually there would be at least some content. The first blank line in the email template file must be between the email header and the email body content.

Those are the only rules:

The email header must have at least a To line.
The first blank line in the email template file must be between the email header and the email body content.

This is an example of an email template file with the minimum header and one sentence for the email body content:

To: me@example.com

This is a content line immediately after the 
first blank line.

Note:

Some hosting companies are configuring their server's emailing software so a Return-Path: header line is required. Therefore, the rest of the examples in this section will have that.

See Troubleshooting Email Sent From Scripts for more information about the various blocks hosting companies have been known to place in the way of outgoing email.

If you request the email address of your form user, you can include that in the email header (assume the form field name where the email address will be typed into is named "visitoremail"):

Return-Path: <[[visitoremail]]>
To: me@example.com
From: [[visitoremail]]
Subject: I got mail!

This is the first line of the email body.

With this arrangement, you will receive the email with the visitor's email address in the From line and all you need to do is click on your email program's "reply" function to send a response — just like you reply to normal email.

If you also request the form user's name, you could put that into the From line, too (assume the form field name where the name is to be typed is named "visitorname"):

Return-Path: <[[visitoremail]]>
To: me@example.com
From: "[[visitorname]]" <[[visitoremail]]>
Subject: I got mail!

This is the first line of the email body.

You can include Cc and Bcc header lines, if you wish to send copies to other destinations:

Return-Path: <[[visitoremail]]>
To: me@example.com
Cc: email2@domain2.com
Bcc: email3@domain3.com, email4@domain4.com
Reply-To: other@example.com
From: "[[visitorname]]" <[[visitoremail]]>
Subject: I got mail!

This is the first line of the email body.

HTML Email

If you want to send HTML email with Master Form V4, format your email body content like an HTML web page. And you also need two additional, special header lines, MIME-Version and Content-Type

Return-Path: <[[visitoremail]]>
To: me@example.com
From: "[[visitorname]]" <[[visitoremail]]>
Subject: I got mail!
MIME-Version: 1.0
Content-Type: text/html; charset="ISO-8859-1"

<html>
<body>
<p>
This is the <u>first</u> paragraph of 
the email body.
</p>
<p>
...
</p>
<p>
This is the <u>last</u> paragraph of 
the email body.
</p>
</body>
</html>

(The charset "ISO-8859-1" could be a different character set, if you wish.)

The order of the header lines doesn't matter so long as the two rules are followed: There must be at least a To header line. And the first blank line occurs between the header lines and the email body.

Attach or Include Other Files

If you want to attach an ebook or other file to the outgoing email, use the ATTACH FileName placeholder.

Similarly, if you want to insert the contents of another file into the outgoing email, use the INSERT FileName placeholder.

Here is an example using both.

Return-Path: <me@example.com>
To: "[[visitorname]]" <[[visitoremail]]>
From: me@example.com
Subject: Your ebook is attached!

[[visitorname]], your ebook is attached.

[[INSERT http://example.com/instructions.txt]]

Thank you for your order.

Sincerely,
The Sales Crew
[[ATTACH originals/ebook.pdf]]

The ATTACH FileName placeholder can be placed anywhere in the email body content section of the email template. If you have more than one attachment, provide an ATTACH FileName placeholder for each.

If your form allows users to upload files, and you are to receive files as email attachments, below is an example that will accept only GIF, JPEG, or PNG files that are no larger than 15 kilobytes in size.

The example assumes the upload form field is named "afile" (where the visitor specifies the file to be uploaded).

Return-Path: <[[visitoremail]]>
To: me@example.com
From: "[[visitorname]]" <[[visitoremail]]>
Subject: I got mail!

Submitted by [[visitorname]] of [[visitoremail]].

[[afile UPLOAD ONLY: gif,jpg,jpeg,png MAXSIZE: 15k]]

The FieldName UPLOAD ... placeholder can be placed anywhere in the email body content section of the email template.

This example will accept any file so long as it does not have an .exe or .scr extension.

Return-Path: <[[visitoremail]]>
To: me@example.com
From: "[[visitorname]]" <[[visitoremail]]>
Subject: I got mail!

[[if_afile]]Uploaded file name: [[afile]]
[[/if_afile]]
Submitted by [[visitorname]] of [[visitoremail]].

[[afile UPLOAD NEVER: .exe, .scr]]

The EMAILS FileName placeholder can be used to extract the emails from a plain text file and insert them, comma separated, into the outgoing email.

This example will extract email addresses from a file named emails.txt, separate them with comma, and insert them into the Bcc header line.

Return-Path: <family@example.com>
To: me@example.com
From: "The Family" <family@example.com>
Bcc: [[EMAILS emails.txt]]
Subject: The latest family news.

Now hear this!
...

Master Form V4 gives you broad latitude in the formatting of your email. You can choose which form information to include in the email and which not to include. You send the email as plain text or as HTML. You can insert files, either verbatim or emails extracted as a comma-separated list. And you can attach files from your server and those that users upload through your form.

NOTE: If you believe you've done everything right, but you never receive the email Master Form V4 is supposed to send, see the Troubleshooting section of this manual for relevant links.

Database Files

To create/update a database, Master Form V4 needs information from two hidden form fields:

filetemplate —
This hidden field specifies the file name of the database record template. This template tells Master Form V4 how to format the record that is to be added to the database file.

If the template file is not in the same directory where Master Form V4 is installed, the hidden field's value must specify the template file's directory location or its URL.
dbfile —
This hidden field specifies the file name of the database to be created or updated. Include the directory location with the file name unless you want the database to be in the same directory where Master Form V4 is installed.

More than one template file, and corresponding database file name, may be specified by putting a comma between each. The number of file templates and database files must be equal to each other.

Hidden field name="filetemplate" —

A database record template is a plain text file representing the record. Placeholders in the template will be replaced with information obtained upon form submission and/or information represented by special placeholders. See Templates, above.

There are many types of databases. One type that you'll probably need at one time or another is a comma-delimited (CSV) flat file database or a tab-delimited flat file database. These flat files are one record per line with the fields separated (delimited) by either a comma or a tab. Sometimes flat file databases use vertical bar characters ("|") as field delimiters. Whatever the type of flat file database you need, Master Form V4 can create and update it for you.

Here is an example vertical bar-delimited flat file database record template:

An example tab-delimited flat file database record template:

And, an example comma-delimited flat file database record template:

In each of the above examples, the database record contains three fields. The first field is the current date in MM/DD/YY format, the month, day, and year represented with placeholders. The second field is a placeholder for the visitor's email address as provided with the form submission (assuming the form field asking for the address is name="email". And, the third field is a placeholder for the form user's IP Address.

Notice that the comma-delimited template has quotation marks around each field. In a CSV file, quotation enclosed fields are optional unless the field itself contains a quotation mark or a comma. If the field contains a quotation mark then, in addition to quotation marks around the field, the comma contained in the field must be doubled up.

Because of the "if's" and special rules, use quotation marks around the fields of a comma-delimited file. If your template is made this way, Master Form V4 will automatically double up any quotation marks contained within the fields. Master Form V4 assumes the record is for a comma-delimited flat file database when it finds a quotation mark at the beginning of the template and a quotation mark at the end of the template.

If you will be storing the contents of any textarea form fields in your flat file database, use hidden field flattenfields to let Master Form V4 know their field names. (See Hidden Fields.)

If you would like to have the field names printed as the first line of the database file when the file is created, put the placeholder

**INITIALIZE_DATABASE_WITH_FIELD_NAMES**

as the first line of the template with the normal template data beginning on the second line. (That's two asterisks on each end instead of two square brackets placeholders normally have.)

You are not restricted to one line per record flat file databases. If you prefer, you can have your data in blocks:

The above example has a row of equal signs as a record separator. Other characters could be used, or a blank line, or no separator at all.

You have control.

Hidden field name="dbfile" —

This hidden field specifies the file name of the database to be created or updated, including the directory path if the file is not to be in the directory where Master Form V4 is installed. In this case, a URL can not be specified in the hidden field, it must be either the file name by itself or the directory path with the file name.

If the directory doesn't exist, Master Form V4 will try to create it. If the directory can not be created, it will send an email to the address specified in the control panel with a guess at what the problem might be and a possible solution.

Here is an example that puts the file named mystuff.db in subdirectory "data"

<input 
   type="hidden" 
   name="dbfile" 
   value="data/mystuff.db">

The above example causes all form submissions to be recorded in the same file, each new record appended below existing records.

If you want each form submission to have its information stored in a separate database file, the file name in the hidden field can have one or more placeholders that would create different file names. For example, this would create a different file according to the email address submitted by users (assuming the form field asking for the email address is name="email"):

<input 
   type="hidden" 
   name="dbfile" 
   value="data/[[email]]_data.txt">

When the file name is created with the placeholder, any non-alphanumeric characters are replaced with an underscore character and any doubled underscore characters are reduced to a single character. Thus, if the email address submitted by the form was willmaster@ExAmple.com, then the file name would be willmaster_ExAmple_com_data.txt

If the willmaster@ExAmple.com address is used in two form submissions, then the second record would be appended below the first in the same willmaster_ExAmple_com_data.txt file name.

If you prefer to keep only the alphabetical characters from the field name, you can precede the form field name with STRIPNONALPHA: OR STRIPNONALPHALC: (the latter turns all characters into lower-case). Example:

<input 
   type="hidden" 
   name="dbfile" 
   value="data/[[STRIPNONALPHA:email]]_data.txt">

Then the file name would then be willmasterExAmplecom_data.txt

And here is an example that turns all characters into lower-case:

<input 
   type="hidden" 
   name="dbfile" 
   value="data/[[STRIPNONALPHALC:email]]_data.txt">

Then the file name would then be willmasterexamplecom_data.txt

To ensure a separate file is created even if the same email address is used in more than one form submission, the SYSTEMTIME placeholder can be used. The SYSTEMTIME placeholder will be replaced with a 10-digit number representing the number of seconds that have elapsed since January 1, 1970. Example:

<input 
   type="hidden" 
   name="dbfile" 
   value="data/[[email]]_[[SYSTEMTIME]].txt">

The above would make a file name something like willmaster_ExAmple_com_1075349872.txt in the subdirectory "data".

Note:

Normally, Master Form V4 creates the database file if it does not yet exist and appends data to the database file if it does already exist.

Master Form V4 can be directed to create a new database file every time the form is submitted, overwriting any file of the same name that might exist. The way to do that is to put this at the top of your database file template:

**OVERWRITE_FILE**

(That's two asterisks on each end instead of two square brackets placeholders normally have.)

"flowto" Templates

When a form is used, Master Form V4 can customize/personalize the next page, whether that page is the next page of a multi-page form (see Multi-page Forms) or the "thank you" page following successful submission of the form. To personalize the page, specify the URL or server directory location of the "flowto" template in the hidden field flowto

(If the page is the "thank you" page and you don't want the page personalized, use hidden field redirect instead of flowto )

A "flowto" template is a web page with placeholders to be replaced with information submitted by the form or other information available to Master Form V4. (See Creating Templates.)

Master Form V4 retrieves the "flowto" template, replaces any placeholders with information available for that placeholder, and then displays the personalized web page from within itself. ("From within itself" means the script generates the page and sends it to the browser. The URL in the browser's address bar will the the URL of Master Form V4.)

Because Master Form V4 displays web pages from within itself and the URL in the browser is the URL of Master Form V4, relative URLs in the web page may not work. The directory where Master Form V4 is installed may be different than the directory where the "flowto" template was retrieved from. When relative URLs don't work, links to images, and CSS and JavaScript files, and other resources including outgoing links might all be broken.

There are two ways to fix the page when links are broken:

Relative URLs can be fixed by putting the
```
<base href="http://example.com/template.html">
```
tag either at the top of the web page source code or as the first line in the HEAD tag. The URL in the BASE tag should be the URL of the "flowto" template.

This will work only if the "flowto" template is at a URL accessible with a browser.

When the BASE tag is encountered, browsers determine relative locations according to the BASE tag instead of according to the location where Master Form V4 is installed.
Relative URLs can be fixed by replacing them with absolute http://... URLs. This should work with all relative URLs except those in SSI tags.

The "flowto" template can be anywhere on the server. Master Form V4 does not require the template to be accessible with a browser.

The use of "flowto" templates make Master Form V4 very versatile. You can format your pages any way you like using any form data you have available and with any other information listed in the table in the Creating Templates section of this user's manual.

Multi-page Forms

Multi-page Forms are possible because some or all of the data collected on the first page of the form is transferred to the second page. And so forth. You can have as many pages as you need for your form — the data keeps coming forward to the next page until the final submit button is clicked.

Multi-page Forms use "flowto" templates (see "flowto" Templates) with one special placeholder:

[[INSERT_HIDDEN_FIELDS]]

<!--INSERT_HIDDEN_FIELDS-->

Wherever you put that special placeholder is where Master Form V4 inserts data from the previous form page — the data is inserted as hidden fields with the same names as on the previous page. Thus, the data gets brought along from one page of your form to the next, but not visible on the page.

This special placeholder does not effect the other template placeholders; you can still use them, or not, as you wish.

There will probably be some information you do not want transferred to the next page. For example, the hidden field flowto should not be transferred unless you are sure you want the same URL in that field as you had in the form on the previous page. You can block the transfer of information in specific fields by using the hidden field nocarry and putting the blocked field names in the field's value separated with commas. Example:

<input 
   type="hidden" 
   name="nocarry" 
   value="nocarry,flowto,use_numbering_key">

Another consideration is that you may want to add the form record to your database only at the last page of the form — unless you have separate databases for previous pages (such as you might if people tend to fill out one or more pages but don't complete all of them; in which case you would at least have the data they provided up to that point). Just put the hidden fields filetemplate and dbfile on the form page(s) where you want to add information to a database.

The data in a multi-page form is cumulative. If your form has many pages, and each page has much information, the number of hidden fields will be large. But that should only be a problem if the web page size exceeds the capacity of the user's browser.

Saving Uploaded Files On The Server

To save files uploaded by form users to your server, the form must have a hidden field named uploadedfilesaveinfo which specifies the location of a plain text file containing one or more [[FieldName UPLOAD ...]] placeholders.

(Examples of the [[FieldName UPLOAD ...]] placeholder are below. For additional information, see the Creating Templates section of this user's manual.)

The hidden field uploadedfilesaveinfo can specify the directory location or the URL of the plain text file. If URL, the domain name in the URL must be the domain name Master Form V4 is installed at.(See Creating Templates)

The plain text file must have one [[FieldName UPLOAD ...]] placeholder for each file uploaded with the form that you want to save to your server. (For clarity, we'll call this plain text file the "Uploaded File Save Information" file.)

If the form allows one file to be uploaded and you want to save that file to your server, there would be one placeholder in the Uploaded File Save Information file.
If the form allows three files to be uploaded and you want to save all of them to your server, there would be three placeholders in the Uploaded File Save Information file.
If the form allows three files to be uploaded and you want to save only two of them to your server, there would be two placeholders in the Uploaded File Save Information file.

Here is an example [[FieldName UPLOAD ...]] placeholder of an Uploaded File Save Information file:

The above assumes the form field name where the user specifies the file to upload is named myupload. The placeholder will save the uploaded file only if the file size is 50k or less. The file will be saved in subdirectory uploads (if the subdirectory does not exist, Master Form V4 will try to create it).

[[FieldName UPLOAD ...]] placeholders in the Uploaded File Save Information file can be broken in multiple lines. Also, any content in the Uploaded File Save Information file that does not look like a placeholder is ignored.

This gives you a lot of room to design the Uploaded File Save Information file, along with the ability to type notes for yourself.

Below is an example Uploaded File Save Information file with [[FieldName UPLOAD ...]] placeholders for three uploaded files. It is assumed that the form field names where the user uploads files are named
fileone
filetwo
filethree
This example Uploaded File Save Information file provides an idea of what can be done, including comments describing each placeholder and placeholders spanning multiple lines.

When uploaded files are saved, they retain their original file name — unless a file by that name already exists in the save directory, in which case the file name is adjusted with a digit. For example, if file mypic.gif was uploaded and a mypic.gif already existed in the directory, then the newly uploaded file would be named mypic2.gif

Custom Error Page

When Master Form V4 encounters an error during form submission, it generates an error page with information about the error. A generic error page is displayed unless you specify a custom error page to use instead.

To specify a custom error page, provide the URL or server directory location of your error page in the hidden field errorpage

The custom error page is a template page, which means Master Form V4 retrieves the page, replaces any placeholders it finds, and then displays the page from within itself. (See the Creating Templates and "flowto" Templates sections of this user's manual for more information about how this works.)

A special placeholder for the error page template is available:

[[ERROR_MESSAGE]]

<!--ERROR_MESSAGE-->

For user-friendly considerations, the placeholder should be present in your error page template.

If the placeholder is not present on your error page template, Master Form V4 can not display specific information about the error that was encountered.

Preventing Cross-Site Scripting

Cross-site scripting (XSS) occurs when a web application gathers malicious data from a user. More information about cross-site scripting can be found here.

The latest version of Master Form V4 is built to to prevent any and all JavaScript, Jscript, HTML, CSS, ASP, or other angle-bracketed tag insertion without your explicit say-so. It also scans for other potentially malicious characters and sanitizes them.

Cross-site scripting protection is an always-on feature. It is intended to pass PCI security scans.

Unless exempted (see further below), all data submitted with a form and immediately stored in a file or printed on a web page is scanned for tags that may contain malicious code. Because not all malicious code can be identified as such, every angle bracket is converted into an HTML entity to render malicious code ineffective.

The reason information stored in a file is also scanned is because the file may be imported into a web page automatically, enabling non-scanned malicious code to render its havoc.

Exemptions —

When certain information submitted from a from needs to be except from the cross site scripting scan, add the form field name to file MasterFormFieldExceptions.cgi

(The correct file name is MasterFormFieldExceptions.pl if Master Form V4 was generated with .pl file name extensions instead of .cgi)

File MasterFormFieldExceptions.cgi is in the directory with the other Master Form V4 software files. It is a plain text file. And it has a .cgi (or .pl) file name extension to hide it from snoopers.

To add (or remove) a field name, download MasterFormFieldExceptions.cgi and edit it with a plain text processor. Then, re-upload the file.

Each exempted form field name needs to be on a line by itself. Blank lines are okay. A line beginning with a "#" character is considered a comment and ignored by Master Form V4.

When a form field name is exempted, it is exempt for all forms using that field name. Therefore, use field names that are unlikely to used intentionally or inadvertently in other forms.

PCI Security Scans

Cross-site scripting security in Master Form V4 is automatically enabled and is intended to have PCI security strength. See Preventing Cross-Site Scripting.

To pass PCI security scans, it may be necessary to white-list the location of template, data, and other files Master Form V4 reads from and writes to when forms are submitted. This is to prevent remote file inclusion.

White-list either no file locations or all applicable file locations.

When no file locations are white-listed, the white-listing functionality is bypassed.

If any file locations are white-listed, then the locations of all files Master Form V4 reads from or writes to during form handling must be white-listed. That would include templates, database files, custom error pages, custom thank-you pages, and uploaded files to be save on the server. (Wild-cards are allowed. See further below.)

How to white-list —

To white-list files, a list of the file locations is put into file MasterFormFileAccessWhitelist.cgi

(The correct file name is MasterFormFileAccessWhitelist.pl if Master Form V4 was generated with .pl file name extensions instead of .cgi)

File MasterFormFileAccessWhitelist.cgi is in the directory with the other Master Form V4 software files. It is a plain text file. And it has a .cgi (or .pl) file name extension to hide it from snoopers.

To add (or remove) file locations, download MasterFormFileAccessWhitelist.cgi and edit it with a plain text processor. Then, re-upload the file.

Specific information —

Blank lines and lines beginning with a "#" character are ignored.

To white-list a file, put the file's location on a line by itself.

List the file location the way Master Form V4 will access it.

If the file is to be accessed as "http://example.com/file.txt" then that is what needs to be listed. If "/file.txt" or "data/data.csv", then list it in that way, not as an http://... URL.

As an example, if you have a custom error page, the hidden field might be:

<input name="errorpage" value="/customerror.html" type="hidden">

The location of the file for white-listing purposes is then
/customerror.html

On the other hand, if the value of the hidden field is an absolute URL, perhaps

<input name="errorpage" value="http://example.com/customerror.html" type="hidden">

Then, the location of the file for white-listing purposes is
http://example.com/customerror.html

Wild-card designations —

File locations may end with an asterisk ("*"). When Master Form V4 sees an asterisk at the end of the file location, it assumes any file location that matches up to the asterisk is white-listed. Example:

templates/*

The wild-card feature is especially useful for file uploads, as the names of the files generally are not known ahead of time. Further, the MFv4Data subdirectory must be white-listed for temporarily holding uploaded files.

If uploaded files are to be stored in directory /uploads then it and the MFv4Data subdirectory can be white-listed for file uploads with these two lines:

/uploads/*
MFv4Data/*