Master Recommend Pro V4

M   A   N   U   A   L

Requirements

To install and use Master Recommend Pro V4, these requirements must be met:

• Your domain server must be UNIX or Linux, have sendmail or qmail available, and have Perl version 5+ installed.
   
• The Perl module LWP::Simple must be available on your server. If it isn't, your hosting company will need to install the module before Master Recommend Pro V4 can be used.
  
  To find out whether or not the Perl module is on your server, you can ask your hosting company or use Master Pre-Installation Tester from http://willmaster.com/master/pit/
   
• To install Master Recommend Pro V4 , you must have and be able to use an FTP program for uploading files, creating directories, and changing permissions.
   

  (Note:

  If your hosting company provides a Control Panel for this purpose, the maximum file size that can be uploaded might be about 32k. Some Master Recommend Pro V4 files are larger than 32k.)

   
  CuteFTP and WS_FTP for Windows, and Transmit for Macintosh, are among the many FTP programs that allow you to CHMOD (change directory and file permissions). These are all available for download at http://tucows.com/

List of Files

{top}

Here is a list of the files you should have received when you generated Master Recommend Pro V4. Depending on how you generated your copy of Master Recommend Pro V4, the files with .cgi extensions may have .pl extensions instead.

LicenseAgreement.html
MRP[CGI]
MRPalways[CGI]
MRPcp[CGI]
MRPdownload[CGI]
MRPmanual.html
README.txt

Here are the files by category:

If you did not receive all of the above files, please write to us at programmer@willmaster.com — include a list of the files you did receive and the domain name Master Recommend Pro V4 was generated for.

Getting Started

{top}

Creating directories
Installing programs
Setting permissions
Initializing the Control Panel
Testing

The Program Directory: This is the directory where the Master Recommend Pro V4 Programs will be installed. It must be in a directory allowed to run CGI programs, probably a directory called "cgi-bin" or something similar.

{up}

{top}

      Creating directories

Master Recommend Pro V4 is a set of programs. You'll probably want to create a directory within your "cgi-bin" to install Master Recommend Pro V4. This will allow you to keep the set of programs separate from other CGI programs you have installed or may install in the future. For example, you might name that directory: mrp

Master Recommend Pro V4 will try to create the data directories it needs. This will work on most servers.

If your server does not allow perl scripts to create directories, here is the procedure for manually creating them:

The Program Directory (named mrp in our example) has a subdirectory. It must be named MRPdata and have global write permission. (See Setting permissions.) Note: Directory and file names are case sensitive.

The MRPdata directory is where the various Master Recommend Pro V4 databases are located.

The MRPdata directory has its own subdirectory. It must be named p and have global write permission. (See Setting permissions.)

The p directory is where the file containing your own Control Panel password is located. (The password will be scrambled and located in a file named "p[CGI]" after your first use of the Control Panel.)

This is how the directory structure might look:

cgi-bin |
        | mrp |
              | MRPdata |
                        | p

Once installed in the mrp directory, Master Recommend Pro V4 will maintain the files in the MRPdata and p directories.

{up}

{top}

      Installing programs

Upload the three program files into the directory you decided upon above. Upload the files as ASCII/plain text and set file permissions (see Setting permissions) as indicated in the following table:

{up}

{top}

      Setting permissions

Permissions can be set via telnet or with some FTP programs. Here are the permission numbers translated into defining attributes:

Some FTP programs use the term "Other" or "Global" instead of the term "World" as used above.

{up}

{top}

      Initializing the Control Panel

When you first type the URL of MRPcp[CGI] into your browser, you will be asked to provide a password. What you type here will be your password for future access to the Control Panel.

After the password screen, the main page will have numerous buttons:

1. Dates — Change the date format if the current selection is not your preference. You can specify month and week day names in any language and format the date output however you wish.

2. Emails — Update the "Email Settings" section with the correct information.

3. Databases — If you want a database record of form activity, update this page.

4. Filters — Here is where you list the words/phrases that may be offensive to recipients.

5. Blocks — Here you can block any email address from "visitor" or "friend" emails that would be sent by Master Recommend Pro V4.

6. Authorized Domains — Here is where you list the domain names and, optionally the IP address, of those domains allowed to use your copy of Master Recommend Pro V4. The domains where the "recommend" forms can be is limited to what you list here. This list can help prevent misuse of your resources.

   Note:

   If you're using the The Form Security Cookie System then only one domain name may have Master Recommend Pro V4 forms — the domain name where Master Recommend Pro V4 is installed. Other domains may be listed here, but their forms must be generated without the The Form Security Cookie System.

7. Form Generation — Answer a few questions and click a button, and Master Recommend Pro V4 will generate a form you can copy and paste into your pages. For more info, see Generating Forms.

8. File Download Information — If you plan to provide temporary file download links on the recommend form "thank you" page, fill in the information in this section, first. For more info, see Custom "Thank You" Pages.

{up}

{top}

      Testing

To test your installation, first generate a form with your control panel. (Access your control panel by typing the URL of MRPcp[CGI] into your browser.)

Once you've generated a form, copy and paste it into a web page. Put the web page on your server and try it out. If things don't work and you can't find the reason, please contact us at Technical Support.

Generating Forms

{top}

Generate forms to copy and paste into your web pages with your control panel.

Access your control panel by typing the URL of MRPcp[CGI] into your browser. When you first type the URL of MRPcp[CGI] into your browser, you will be asked to provide a password. What you type here will be your password for future access to the Control Panel.

Once at your control panel, click the "Form Generation" button.

You'll see a form to fill in. Master Recommend Pro V4 remembers the form contents from the most recent use, so if you need to make changes it is easily done.

Here is a short synopsis of each of the form fields:

1. What is the URL to your installation of MRP[CGI]?
   This will be the same for all of your forms, the complete http://... URL to your installation of MRP[CGI]
   
 
2. What is the name of the site/page/product being recommended?
   You can have a different "recommend" form for different pages or products, if you want. Here, type in the name or title of that which will be recommended.
   
 
3. What is the http://... URL of the site/page/product being recommended?
   Here, type in the complete http://... URL of that which will be recommended.
   
 
4. The form shall have room for how many friends' name and email addresses?
   Type a number to tell Master Recommend Pro V4 how many people your visitor can recommend when using your form. Master Recommend&Pro has no upper limit. Your server, however, does. If you use a large number here and find that your server takes a long time to generate and email the recommendations, you may wish to use a smaller number. When deciding what number to use here, consider that the "thank you" page may have another recommend form with the visitor's name, email address, and message already filled in.
   
 
5. Is every available friend name/email space required to be filled in?
   If you require a certain number of recommendations in exchange for something of value, like a download or access to a restricted area, then you will want to check "Yes." Otherwise, it may be prudent to allow your visitors to recommend less friends than the form has room for.
   
 
6. How many vertical columns of name and email address sets shall the form have?
   The number you type here will tell Master Recommend Pro V4 how to arrange the friends' name and email address fields of the form. The fields for the visitor's name and email address will be at the top of the left-most column.
   
 
7. How wide (number of characters) shall the name and email form fields be?
   Specify the width of the name and email address form fields. If the visitor uses more space then the width you specify here, the entry will scroll to the left.
   
 
8. If you do not use CSS and if you want the font name/size/color to be different than default, type them here.
   If you use CSS on the page with the recommend form, the font attributes will conform with your specification for TD. However, if you do not use CSS, you may use these spaces to specify font attributes different than the default. The font "Name:" may be a comma-separated list, like "arial,helvetica,sans serif" but the "Color:" and "Size:" may have only one value. All of these attributes are optional; you may use none, one, two, or all.
   
 
9. If the visitor shall have the option of sending a message to the friend(s) s/he recommends, type the height (number of lines) and width (number of characters) here. If the visitor shall not have that option, leave the height and width blank.
   You may provide a message area where the visitor can write a personal note to the friends being sent a recommendation. If you want to provide that message area, specify the height and width here. Otherwise, leave the height and width blank.
   
 
10. Shall there be a checkbox where the visitor can request a copy of what is sent to the friends?
    When a copy of what is sent to friends is provided to the visitor, only one copy is sent even if more than one friend is receives a recommendation. The copy, where the friends' name and email address would be in the recommendation email, has a notation that "friend's name goes here" and "friend's email address goes here" wherever that information would be. Select "Yes" or "No" to specify whether or not the visitor may request a copy.
    
 
11. What is the http://... URL of the template confirmation/thank you page?
    Type the complete http://... URL of the "thank you" page the visitor will see after submitting the recommend form. (To make custom "thank you" pages, see Custom "Thank You" Pages.)
    
 
12. What shall be the text on the submit button?
    Specify what words will be on the form's submit button.

Once the form is filled in and you click the "Generate the Form" button, Master Recommend Pro V4 will generate the HTML code for the form. Copy and paste the HTML code into your web page.

Master Recommend Pro V4 will also generate a custom "thank you" page complete with form contain codes where the visitor's name, email address, and form message may be displayed. See Custom "Thank You" Pages before making changes to the generated page.

Custom "Thank You" Pages

{top}

A Custom "Thank You" Page is a template.

There are three considerations when making a template page for use by Master Recommend Pro V4. Except for those two considerations, template pages are just like regular web pages.

1. All URLs on the template page except URLs in SSI tags must be complete http://... URLs. This means image src="________" attributes, link href="________" attributes, external style sheet URLs, URLs to external JavaScript files, the URLs in <form action="________" attributes — all URLs except in SSI tags.
   
   The reason is that the template page will be retrieved and then generated from within Master Recommend Pro V4, and doing that could make relative URLs point to the wrong directories. URLs in SSI tags are exempt because the SSI content is included before Master Recommend Pro V4 receives the template.
   
   Alternatively, put the absolute http://... URL of the "thank you" page into an BASE tag at the top of your source code. I.E.

   <BASE HREF="http://example.com/thankyou.html">

   The BASE tag will cause the browser to use that URL as a base to determine the relative directory instead of the location of Master Recommend Pro V4.
   
 
2. Placeholders may be used to place information collected from the previous form. Where the placeholder is found on the template page, there Master Recommend Pro V4 will insert the information provided in the previous form. In the table below is a list of placeholders and the type of information they will be replaced with.
   

   This placeholder	will be replaced with
   [[VISITORNAME]]	The name the visitor provided for self when last recommending to friends.
   [[VISITORMAIL]]	The email address the visitor provided when last recommending to friends.
   [[MESSAGE]]	The message the visitor typed when last recommending to friends.
   [[SITENAME]]	The name of the site last recommended.
   [[SITEURL]]	The URL of the site last recommended.
   [[DATE]]	The date of the last recommendation.
   [[IP]]	The IP address of the visitor when the last recommendation was made.
   [[FORMURL]]	The URL of the form last used by the visitor.

3. If you are providing a temporary download link on the "thank you" page, this placeholder needs to be used so Master Recommend Pro V4 where to insert the URL:

   [[DOWNLOAD filename.zip]]

   Replace filename.zip with the file name of the original download file.

   Wherever that placeholder is found on the "thank you" page, Master Recommend Pro V4 will replace it with a temporary download URL. Here is an example of it's use:

   <p>
   Your download file is at 
   <a href="[[DOWNLOAD filename.zip]]">[[DOWNLOAD filename.zip]]</a>
   </p>

   If you wish to offer a temporary download link to more than one file, you might do something like this:

   <p>
   Your download file is at 
   <a href="[[DOWNLOAD filename1.zip]]">[[DOWNLOAD filename1.zip]]</a>
   </p>
   <p>
   <a href="[[DOWNLOAD filename2.zip]]">Click Here</a>
   for your other free gift.
   </p>

The Form Security Cookie System

{top}

The Form Security Cookie System was developed specifically for forms that, by their very nature, require that the email address of a message receiver be specified by the form user. It is designed to prevent automated submission of the recommend form by spammer's or cracker's programs.

When you generate a recommend form, you can decide whether or not to use the Form Security Cookie System. To use the system, specify the domain name where Master Recommend Pro V4 is installed in the form field provided. To not use the system, omit the domain name.

The generator will generate all necessary code.

This is how the Form Security Cookie System works:

1. When the form is loaded into the user's browser, JavaScript determines a unique value for a cookie. It then:

1. Sets a cookie with that value in the user's browser. (The cookie can be read only by the domain that set it, which must be the same domain name that's specified in the JavaScript code itself.)

2. Stores the cookie value in the form's hidden field name="sc"

2. When the form is submitted, the cookie's value is submitted to Master Recommend Pro V4 along with the rest of the form values.

3. If Master Recommend Pro V4 has been told to validate the security cookie, which information is stored on the server in a location specified by hidden field name="which", it then:

1. Verifies that a security cookie exists and that its value matches what arrived in the form's hidden field name="sc"

2. Verifies that the same security cookie has not previously been used. (In the control panel where the recommend form is generated, Master Recommend Pro V4 allows you to specify how long to remember previously used cookies.)

3. Changes the browser security cookie's value to "already used".

Because it works the way it does, the Form Security Cookie System requires that the recommend form and the Master Recommend Pro V4 both reside on the same domain. If you wish to have recommend forms on other domains, the forms must either be generated without the security cookie protection or Master Recommend Pro V4 must be licensed and installed on those domains.

Technical Support

{top}

Technical support is available by email at programmer@willmaster.com — please include your domain name, a description of the problem, and any information you think might help us resolve the situation. When time is of the essence, our telephone number is listed at http://BontragerConnection.com/contact.shtml (note that we travel a lot, so there will be periods when we're out of cell phone range).

If you desire to have us install Master Recommend Pro V4 for you, custom installation information can be found at http://willmaster.com/master/installation.shtml

Thank you for your purchase of Master Recommend Pro V4.

Copyright 2001 William Bontrager
Copyright 2002-2004 Bontrager Connection, LLC