dB Masters FormM@iler Documentation


INSTALLATION AND BASIC CONFIGURATION

  1. FormM@iler has only a single hidden field named "config". The value of this field will call the appropriate list of configuration options from formmailer.php to process the form. If the config field has a value="0" then it will use the configuration options that are listed with a [0] after the variable name. This is done to keep all information stored safely on the server to eliminate the liklihood of comprimising the script by spammers.

  2. Open the file formmailer.php with a text editor and find the line near the top:

    • $tomail[0]="you@yourdomain.com";
      Change you@yourdomain.com to your e-mail address (with quotation marks)

    • $mail_fields[0]="list,of,fields";
      Change list,of,fields to a comma delimited list of which fields you want in the resulting email and in the order you want them in

  3. Upload form.php and formmailer.php to the same directory on your webserver. You do not need to chmod (change mode) any files.

  4. You are finished. Point your browser to form.php on your website!

Noteworthy comments:

  • Note: The "action" property of the form is set to assume form.php and formmailer.php are in the same directory (action="formmailer.php"). If you want to put your form page and formmailer.php in different directories, that's fine, just make sure the action value in the form tag still points to formmailer.php, for instance: <form id="form" method="post" action="scripts/mail/formmailer.php">

  • If you plan to use the file attachment option enctype="multipart/form-data" must be added to the form tag.

  • You do not have to use form.php as your form, you can point any form, of any extension, to formmailer.php and it will work just the same. form.php and form2.php are simply provided as quick-start templates.


ADVANCED OPTIONS


DEFAULT ERROR MESSAGES

FormM@iler allows you to use custom error and success pages to link to via variables discussed further down in the document, however, if you choose to use the default error pages for the benefit of more specific errors messages and simplicity, you can also define exactly what the default messages are with the variable listed below:

Reopen the file formmailer.php and find the lines:

$error_page_title - The title of the error page.
$error_page_text - The text of the error page (in addition to the actual errors themselves).
$thanks_page_title - Title of the success page.
$thanks_page_text - The text of the success page.


CHARACTER SET

FormM@iler now supports any language that has a character set.

$charset[0]="UTF-8";

iso-8859-1 supports most standard ASCII single-byte languages for special double-byte languages, change this value to the approporiate charset for the language. FormM@iler defaults at UTF-8 which is unicode and hopefully works, by default with most any language.

MULTIPLE RECIPIENTS

You can have email sent to multiple recipients. In addition, you can send carbon copy (cc) email and blind carbon copy (bcc) email to multiple recipients. Just separate the addresses with commas.

Reopen the file formmailer.php and find the lines:

$tomail[0]="you@yourdomain.com";
$cc_tomail[0]="";
$bcc_tomail[0]="";


Designate more recipients by adding their email addresses separated by commas:

$tomail[0]="sales@aceplastics.com,admin@aceplastics.com,records@aceplastics.com";
$cc_tomail[0]="pres@aceplastics.com,sevice@aceplastics.com";
$bcc_tomail[0]="myhome@erthlink.com,myjunk@hotmail.com";


The last of the group above ($copy_from[0]="noreply@yourdomain.com") is something different and should only have one email address, if any. That is explained under "COPY TO SENDER" below.


COPY TO SENDER

You can choose to have a copy of the email the visitor sends sent to the visitor also. Open formmailer.php and find the lines. (again, where the number inside [] matches the number of the config hidden field for that form).

The one limitation of email going back ot the sender is that you can not send any attached file back to the sender.

  1. $send_copy[0], change the value to "yes" to turn this feature on.
  2. $send_copy_format[0], sets the layout of the email. Options are "vert_table" or "horz_table", anything else will result in plain text email
  3. $send_copy_fields[0], has a comma-delimited list of the fields you want to include in the copied email, in the order you want them displayed.
  4. $copy_subject[0], enter the words you want to appear in the subject line of the email returned to the visitor.
  5. $copy_intro[0], is the custom intro text that appears at the top of the email body.
  6. $copy_from_email[0], indicates the email address of the sender of the copy.
  7. $copy_from_name[0], indicates the name of the sender of the copy.
  8. $copy_tomail_field[0], you want set the the name of the field which the user entered their email address.

COMPLETE LIST OF OPTIONS

Option Name Description
$charset[0] character set code for the email
$tomail[0] list of recipients
$cc_tomail[0] list of carbon-copied recipients
$bcc_tomail[0] list of blind carbon-copied recipients
$subject[0] the subject of the email to be sent
$reply_to_field[0] the name of the field that should be put in the "from" field of the email as the address the message is coming from.
$reply_to_name[0] the name of the field that should be put in the "from" field of the email as the name of the person or place the message is coming from.
$required_fields[0] a comma separated list of fieldnames you require to be filled in
$required_email_fields[0] a comma separated list of fields to be validated for valid email address syntax
$attachment_fields[0] comma delimited list of the fields of the form that are file attachment fields
$return_ip[0] do you want the IP of the sender returned with the email if available? yes/no
$mail_intro[0] header text for recipient email
$mail_fields[0] list of the fields of the form that you want sent to the recipient list, in the order you want them displayed
$mail_type[0] layout of email options are "horz_table" or "vert_table", anything else will result in a plain text email
$mail_priority[0] 1 is high, 3 is normal
$send_copy[0] whether to send a copy of the mail to the sender
$send_copy_format[0] layout of email sent back to sender options are "horz_table" or "vert_table", anything else will result in a plain text email
$send_copy_fields[0] which fields get included in the send_copy email
$send_copy_attachment_fields[0] comma delimited list of the fields of the form that are file attachment fields to be returned to the sender
$copy_subject[0] subject of sent copy
$copy_intro[0] Header text for autoresponder email
$copy_from_email[0] Email address the autoresponder comes from
$copy_from_name[0] Name the autoresponder comes from
$copy_tomail_field[0] field of email address to the sender for the sent copy
$header[0] absolute or relative path to a file you wish to include as a template header
$footer[0] absolute or relative path to a file you wish to include as a template footer
$error_page[0] the filename (and path if necessary) to a custom error page, if missing or blank default text in variable above will be used
$thanks_page[0] the filename (and path if necessary) to a custom thanks page, if missing or blank default text in variable above will be used


HANDLING FILE UPLOADS

DO NOT add the name of the attachment field to the $mail_fields list.

Enter the file attachment field names in the $attchment_fields variable as a comma-seperated list. To control the size allowed in the uploads add the hidden field <input type="hidden" name="MAX_FILE_SIZE" value="30000"> before the first field. This is a PHP function that will limit the size of the filed, the value being the maximum byte size allowed for any file attachment field.

Also note that if you plan to use the file attachment option enctype="multipart/form-data" must be added to the form tag.


FORM NOTES, TRICKS AND PHP TIPS

Note that each form does not have to end in PHP, the form page itself can have any extension, but formmailer.php MUST retain it's php extension and the action of the form must point to it.

Note that any form field that could contain multiple selection, such as a multi-select dropdown menu, or checkboxes of the same name must end their name with brackets []. This is a requirement of PHP so the PHP interpreter knows to expect the possiblity of several answers!

DO NOT use spaces in the field names of your form. A good option is to use an underscore ("_") instead.

The config hidden field may seem confusing, but it is done this way to prevent spambots from harvesting actual email addresses from hidden fields the way many scripts do.

It is possible to have a selectable recipient list by making your config field a select type form field like so:
<select name="config">
<option value="0">Sales</option>
<option value="1">Support</option>
<option value="2">Marketing</option>
</select>
which makes the config value variable upon the choice of the user.


USAGE LICENSE AGREEMENT

  • You can freely use the script and modify it all you wish, but always retain the copyright notice in each file, and the visible link to the FormMailer homepage in the any form using the FormMailer as shown in the form.php sample.
  • You can sell or freely distribute your modified version of this script so long as dB Masters copyright and link stay in tact.
  • You can, for $20 per domain, purchase the right to remove the link

HTML Form Samples


Basic Form

Your Name

Your Email

Comments and/or Questions


Here is the html code for the above form:

<form id="form" method="post" action="">
<p>Your Name<br /><input type="text" name="Name" value=""/></p>
<p>Your Email<br /><input type="text" name="Email" value="" /></p>
<p>Comments and/or Questions<br /><textarea name="Comments" rows="5" cols="40"></textarea></p>
<p>
<input type="submit" name="submit" value="Submit" />
<input type="reset" name="Reset" value="Clear Form" />
<input type="hidden" name="config" value="0" />
</p>
</form>

More Elaborate Form

Your Name

Your Email

Regarding

Where are you gonna use this script?
At Home
At School
In the car

How old are you?
Less than 18
19-25
Over 25

Comments and/or Questions


Here is the html code for the above form:

<form id="form" method="post" action="formmailer.php" enctype="multipart/form-data">
<p>Your Name<br /><input type="text" name="Name" value=""/></p>
<p>Your Email<br /><input type="text" name="Email" value="" /></p>
<p>Regarding<br />
    <select name="Regarding">
    <option value="This cool script">This cool script</option>
    <option value="Some other cool script">Some other cool script</option>
    </select>
</p>
<p>Where are you gonna use this script?<br />
    <input type="checkbox" name="Where_to_use[]" value="Home" /> At Home<br />
    <input type="checkbox" name="Where_to_use[]" value="School" /> At School<br />
    <input type="checkbox" name="Where_to_use[]" value="In the car" /> In the car
</p>
<p>How old are you?<br />
    <input type="radio" name="Age" value="Under 18 <" /> Less than 18<br />
    <input type="radio" name="Age" value="19-25" /> 19-25<br />
    <input type="radio" name="Age" value="Over 35" /> Over 25
</p>
<p><input type="file" name="attachment" /></p>
<p><input type="file" name="attachment1" /></p>
<p>Comments and/or Questions<br /><textarea name="Comments" rows="5" cols="40"></textarea></p>
<p>
<input type="submit" name="submit" value="Submit" />
<input type="reset" name="Reset" value="Clear Form" />
<input type="hidden" name="config" value="0" />
</p>
</form>