Documentation Tell A Friend Script

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

Introduction

For security reasons the script can only be called by a link from an HTML page. While doing this the script checks the referrer and compares it with the configuration. If the referrer and the allowed referrer match the script will be executed.

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';

I case you have added your server name to the variable and are still seeing this error message please make sure, that you opened the script by clicking on a link at your website (Tell A Friend).

More variables in the 'index.php':

$language     Enter here the abbreviation of the language (i.e.: en or de). The language files are stored in the folder 'languages'.

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

$sender_count     You can determine how often within a certain time range the sender is allowed the send recommendations with the same e-mail address. Enter the number of e-mails that a sender can send with the same e-mail address (0 turns the function off).

$sender_duration     Definition of the time range in hours (1, 2, 5, 10, 20, 300). After that time range the user can use the e-mail address again.

$recipient_count     Like above you can determine how often within a certain time range a page can recommended to the same e-mail address. Enter the number of e-mails with the same recipient e-mail address (0 turns that function off).

$recipient_duration     Definition of the time range in hours (1, 2, 5, 10, 20, 300). After that time range the user can send recommendations to that e-mail address again.

$ip_address_count     The third option is to connect the number of e-mails to the IP address of the user. Like the two options above you can determine the number of e-mails and the time range. 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) turns this function off.

$ip_address_duration     Definition of the time range in hours (1, 2, 5, 10, 20, 300). After that time range or after the next dial-in to the internet the user can send e-mails again.

When you turn one of those features on, the logging function will be turn on too. Please make sure that the directory 'logs' and the log file itself ('logs/logfile.txt') have writable permissions (chmod 777).

$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).

$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/.../tell_a_friend/templates/). Please pay attention to the ending slash.

$file['default_html']     This variable contains 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.

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 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 placeholders are not included in the language file and should not be changed.

{check_referer}
{check_server}
{message}
{redirect}
{referer}
{server}
{link}

Form Fields

For every form field name in the template exists automatically a placeholder with the same name that can be used within the HTML template and the mail template as well.

The script uses three pre-defined form fields. The following field can also appear as a radio button:

<input type="hidden" name="link" value="{redirect}" />

The other two fields:

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

You can add more fields to the form but do not change the three mentioned above. Please make sure that those additional field names and placeholder names do not contain white spaces or special characters.

Example:

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

Mandatory Form Fields

Every form field can be marked as mandatory field. The form will not be submitted until the form has been filled in. 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, sender_email, friend_email" />

E-mail Syntax

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

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

Example:

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

Redirect Back or Thank You Page

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

<input type="hidden" name="redirect" value="{redirect}" />

In case you want to redirect the user to a certain page just replace the placeholder {redirect} with the URL of the thanks page.

Example:

<input type="hidden" name="redirect" value="thanks.html" />

Mail Template

The mail template can be defined in this hidden form field:

<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" />

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: {friend_email}
    

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: {sender_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.

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 Tell-A-Friend Script for free. If you want to run the script without the link to STADTAUS.com you can purchase the full version online (US$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. Formmail Script
  4. Google Dance Tool

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

http://www.metacollection.com/

Back To Top

Support

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

Back To Top