Documentation Formmail Script

Thank you for your interest in our Formmail Script. We recommend to read this documentation carefully.

Introduction

It is important that the script will be called from a form or from a link on your website. That is for security reasons. The script checks the referring site and compare it with the information from the script configuration. In case it fits the script will be executed.

You can use the script in a direct (the link) and indirect way (the form). The direct way is to link to the file 'index.php' directly and use the default templates (HTML and mail).

The indirect way uses already existing forms within a HTML page. With this method you are able to process several forms with the same script. HTML, mail templates, and all the further parameters are defined through hidden form fields within the HTML form.

The HTML template of the script have been generated by the specifications of XHTML 1.0. HTML tags like <br> or <input> contain an ending slash (<br /> or <input type="text" name="field" />).

Set up and configuration

If you open the script in your browser and get the error message 'Wrong or empty referrer (referring site)!', you will have to add the name of your server to the variable '$referring_server' in the file 'index.php'. The name of the server is usually the domain (enter it with and without www). Additionally you can add the IP address to the variable.

Example:

$referring_server = 'www.your-server.com, your-server.com, 127.0.0.1';

The indirect way uses already existing forms within a HTML page. With this method you are able to process several forms with the same script. HTML, mail templates, and all the further parameters are defined through hidden form fields within the HTML form.

$language     You can set here the language. Enter here the abbreviation that also is used in the name of the language file in the directory 'languages' (en in languages.en.inc.php and de in languages.de.inc.php).

The following features has also been designed to prevent the abuse of the script by a third party (spammer). You can connect the number of e-mails to the IP address of the user.

$ip_banlist     This variable can contain IP addresses of servers that you do not want to access your Formmail Script. If you do not want to use this feature, just leave the variable empty.

$ip_address_count     Enter here the maximum number of e-mails which a user can send through the form. Once the user has reached this number he can send more e-mails after the next dial in to the internet. The number 0 (null, zero) set this function off.

When you set this feature on the logging function well be set on too. Please make sure that the directory 'logs' and the log file itself ('logs/logfile.txt') have writable permissions (chmod 777).

$ip_address_duration     This variable sets the time duration for the maximum number of e-mails. After that duration the user can send e-mails again.

$show_limit_errors     Once the user has reached the maximum number of e-mails you can show him an error message.

$log_messages     With this variable you can set the logging function on or off. If you want to use this feature please make sure that the directory 'logs' and the log file itself ('logs/logfile.txt') have writable permissions (chmod 777).

$text_wrap     This variable contains the number of characters after that a line break will be added automatically. In case no value is defined, no line break will be added.

$show_error_messages     The default value of this variable is 'yes' so during the configuration process you will get error messages and hints that help you to install the script. Once the script configuration have been finished you can set off these system messages because it is not necessary to give extern visitors a view in the system.

$path['logfile']     This variable contains the path to the log file.

$path['templates']     This variable contains the path to the template files (HTML and mail). The path can be relative (./templates/ or templates/) and absolute (i.e.: /usr/local/etc/httpd/.../formmail/templates/). Please pay attention to the ending slash.

$file['default_html']     If you want to use the script in the direct way this variable must contain the file name of the HTML template. This template will then be used automatically.
$file['default_mail']     If you want to use the script in the direct way this variable must contain the file name of the mail template. This template will then be used automatically.

$add_text     You can add further values, text, variables or other content to this variable. That content can be displayed in the HTML templates by using markers/placeholders within curly brackets { and }.

If you want to add your own values to the variable $add_text please follow the pattern from the example entries.

$add_text = array(

                    'txt_additional' => 'Additional',
                    'txt_more'       => 'More'

                  );

           
The first part of each entry is the name of the placeholder. In case you want to use the value of txt_addition in your template enter the name of the entry with curly brackets - {txt_addition}. The name must not contain white spaces or special characters. Only allowed is the _ .

Back To Top

HTML template customization - templates/form.tpl.html

The directory 'templates' contains the files for the layout. You can use HTML and CSS to customize the layout as you wish.

In case you are using a WYSIWYG editor like Dreamweaver, Frontpage or NetObjects please make sure that the software does not make any changes by itself.

The subfolder 'examples' contains further HTML forms. You can use them as example for you own forms. With the template 'alternative_form.tpl.html' you can let the visitor choose, if he wants to recommend the page he just have visited or if he wants to recommend the homepage. And the template 'advanced_form.tpl.html' contains examples how to integrate checkboxes, radio buttons and select menus in your form.

The template files contain markers with { and } like: {txt_next_page}. These markers will be replaced by its counterparts from the language file 'languages/language.en.inc.php'. You are free to edit that file and change the words and phrases. You are also free to replace the markers within the template files by real words or put those markers to other positions within the template file. And you are also able to enhance the language file by using the given pattern.

Following placeholder is not included in the language file and should not be changed.

{message}

Form Fields

For every form field name in the template exists automatically a placeholder with the same name. That is to show the values of the form fields when an error occurs.

Example:

<input type="text" name="lastname" value="{lastname}">

You can add more fields to the form or change the existing. Please make sure that field name and placeholder name do not contain white spaces or special characters.

Mandatory Form Fields

Every form field can be marked as mandatory field. The form will not be submitted until the form is filled in correctly. Enter all mandatory field names in following hidden form field in the template:

<input type="hidden" name="required_fields" value="" />

Example:

<input type="hidden" name="required_fields" value="lastname, email, subject" />

E-mail Syntax

Like the mandatory fields you can define fields that you want to be checked for a right e-mail syntax.

<input type="hidden" name="email_fields" value="" />

Example:

<input type="hidden" name="email_fields" value="email" />

Thank You Page

After the form has been submitted the user will be redirected to a page you can define in the following field:

<input type="hidden" name="thanks" value="" />

Example:

<input type="hidden" name="thanks" value="http://www.your-server.com/thanks.html" />

Please enter the hole URL including http:// and the domain name (i.e.: http://www.your-domain.com/).

Define HTML Template

You can open the script directly in your browser (call index.php) or call the script from an existing form in a HTML page. In the latter case you will have to define the HTML template in the following field:

<input type="hidden" name="html_template" value="" />

Example:

<input type="hidden" name="html_template" value="form.tpl.html" />

Define Mail Template

The mail template can be defined the same way:

<input type="hidden" name="mail_template" value="" />

You can define one single mail template,

<input type="hidden" name="mail_template" value="mail.tpl.txt" />

or you can define more than one mail template. Each of these templates can contain different recipients and contents:

<input type="hidden" name="mail_template" value="mail.tpl.txt, mail2.tpl.txt" />

Select Menus

The script can process select menus like the following:

<select name="" size="">
  <option value=""></option>
  <option value=""></option>
</select>

An exception are multiple select menus.

How to make sure the value selected by the user appears after a new load of the form shows the following example:

<select name="Salutation" size="2">
  <option value="Mr" {select:Salutation=Mr}>Mr</option>
  <option value="Ms" {select:Salutation=Ms}>Ms</option>
</select>

The placeholder {select:Salutation=Ms} contains of the following elements. At the first place stands the type of form field you are using. In this case it is a select menu (= select). After that follows a :. At the second place stands the name of the form field. In the example above that would be "Salutation". After that follows an equal sign (=). At the last place stands the value of the option tag (value="").

To make the selected value appear within the mail template, you need to enter the name surrounded by curly brackets - { } - in the mail template.

Checkboxes

The script can process checkbox fields like the following:

<input type="checkbox" name=" " value="" />

How to make sure the value selected by the user appears after a new load of the form shows the following example:

<input type="checkbox" name="Newsletter" value="Yes" {checkbox:Newsletter=Yes} />

The placeholder {checkbox:Newsletter=Yes} contains of the following elements. At the first place stands the type of form field you are using. In this case it is a checkbox field (= checkbox). After that follows a :. At the second place stands the name of the form field. In the example above that would be "Newsletter". After that follows an equal sign (=). At the last place stands the value of the option tag (value="").

To make the selected value appear within the mail template, you need to enter the name surrounded by curly brackets - { } - in the mail template.

Radio Buttons

The script can process radio button fields like the following:

<input type="radio" name=" " value="" />

How to make sure the value selected by the user appears after a new load of the form shows the following example:

<input type="radio" name="Salutation" value="Mr" {radiobutton:Salutation=Ms} />

The placeholder {radiobutton:Salutation=Ms} contains of the following elements. At the first place stands the type of form field you are using. In this case it is a radio button field (= radiobutton). After that follows a :. At the second place stands the name of the form field. In the example above that would be "Salutation". After that follows an equal sign (=). At the last place stands the value of the option tag (value="").

To make the selected value appear within the mail template, you need to enter the name surrounded by curly brackets - { } - in the mail template.

Examples of the above described features can be found in the template "advanced_form.tpl.html".

Back To Top

E-mail Template Customization - templates/mail.tpl.txt

At the top of the mail template are the header data like:

      Recipient           To:
      Sender              From:
      Subject             Subject:
      Carbon Copy         CC:
      Blind Carbon Copy   BCC:
    

You can define the e-mail recipient within the template like this:

      To: name@your-server.com
    

Additionally, you can add several recipients with carbon copy and blind carbon copy:

      CC: name@other-server.com
      CC: chef@company.com
      BCC: secret@company.com
    

The sender can be defined within the mail template or you can use the information from the form:

      From: {email}
    

You also can add the name of the sender. In this case the name is followed by the e-mail address which stands between angle brackets.

      From: {firstname} {lastname} <{email}>
    

Below the e-mail head area (header) follows an empty line (two line breaks) and below that line follows the mail content. You can customize the mail content as you like. If you add fields to the form you will have to place the name of those fields within curly brackets in the mail template.

Display all form data with one placeholder

You are able to display all form data with only one placeholder. Just add the placeholder

      {all_content}
    

to the e-mail template.

Environment variables and server date and time

The following environment variables are provided by the script. To make these variables appear within the e-mail you can use following placeholders:

{env_user_agent}     Browser software of the user (Mozilla, Netscape, Opera, Internet Explorer).

{env_remote_address}     IP-Address of the user.

{env_remote_host}     Host name of the user.

{env_year}     Year

{env_month}     Month

{env_day}     Day

{env_hour}     Hour

{env_minute}     Minutes

{env_second})     Seconds

Back To Top

The Log File - logs/logfile.txt

The directory 'logs' and the file 'logfile.txt' must be writeable (chmod 777).

Back To Top

License Information

You can use the Formail Script for free. If you want to run the script without the link to STADTAUS.com you can purchase the full version online ($15/15 Euro).

The full version includes free updates and upgrades.

  1. You may re-distribute the script license to a third party.
  2. You may stipulate your own price.
  3. The script license applies for a single domain.

Contact: http://www.stadtaus.com/en/

More Scripts at STADTAUS.com:

  1. Image Gallery Script
  2. Online Appointment Planner
  3. Google Dance Tool
  4. Tell A Friend Script
  5. Download Script

Please visit our project MetaCollection. It is a resource for CGI and PHP related script archives.

http://www.metacollection.com/

Back To Top

Support

Answers to your questions and solutions for your problems with the script you will find in our support forum.

Back To Top