Required Files
Readying Script
Readying Email Templates
Uploading Complete Program
Creating a Form
The Form Security Cookie System
Verification and Trouble Shooting
Custom Installation
Pointers For Better Results
Staying Current
Contact Us
|
When you're ready to upgrade, here are a few of the features built into
Master Recommend V3 Pro:
- Dates language and format, email templates, and initialization are all handled with
a control panel with your web browser.
- Through the control panel, you maintain your own list of offensive words/phrases. Wildcard characters are allowed.
- If your installation is misused or you receive requests to cease mailing to certain destinations, the control panel makes it easy to specify banned email addresses.
- The program has no limit on the number of friends that can be recommended.
- Form data may be recorded in a database in addition to, or instead of, in a notification email to the webmaster.
- The "thank you" page can be personalized. It can also contain another recommend form with the visitor's name, email address, and message to friends already filled in.
- Recommend forms can be generated with the control panel, with handy formatting options. Just copy the generated forms and paste them into your web pages.
A demonstration of the control panel is linked from
the Master Recommend V3 Pro product page.
|
Master Recommend V3 now assists in spam-proofing your website,
is multi-lingual, lets you insert the referring URL (the url of the form) into outgoing emails,
lets you insert the IP address of form users, and has form hijacking code.
Before installing and/or using Master Recommend V3, you must agree to the complete
license agreement, linked
from http://www.willmaster.com/master/recommend/
You may use the navigation bar at the left to jump to the section of your choosing, if you wish. At the end of each section is a link to jump back up here to the top of the manual.
The following files are required with each distribution of Master Recommend V3:
| MasterRecommendV3.html |
This manual that you are reading. |
| LicenseAgreement.html |
The license agreement that you must agree to before installing and/or using
Master Recommend V3. If this file differs from the latest version linked from
http://www.willmaster.com/master/recommend/, then
the version linked from
http://www.willmaster.com/master/recommend/
prevails |
| emailtemplate.txt |
The file containing the templates for emails sent to your site visitor, the visitor's friend, and to yourself. |
| MasterRecommendV3.cgi |
Master Recommend V3 program written in Perl 5. It may be renamed so long as it retains an extension recognized by your system as being an executable Perl CGI file. Extensions .cgi or .pl are the usual choices. |
[TOP OF PAGE]
Use a word processor which edits and saves text in ASCII/plain text format when making changes. NotePad, BBEdit Lite, and Pico all work fine.
Modify the first line of MasterRecommendV3.cgi to reflect the location of perl version 5+ on your system. The line must begin with the two characters #! and then the location of Perl 5. The line should have no spaces.
Below the copyright notice are several items to customize.
Use a word processor which edits and saves text in ASCII/plain text format when making changes. NotePad, BBEdit Lite, and Pico all work fine.
Unless otherwise specified, values for the following customization steps are between
single quote characters. If a single quote character is required within the value,
precede it with a backward slash. Example: \'
Here is a list of NAMEs and VALUEs which Master Recommend V3 requires:
| Example line in MasterRecommendV3.cgi script file |
| NAME |
VALUE |
| G{MailProgram} = '/sbin/sendmail -t'; |
| MailProgram |
The location and name of your systems mailer. Include any required flags, such as sendmail's "-t" |
| $G{ErrorAddy} = 'errors@example.com'; |
| ErrorAddy |
The email address where any error messages are to be mailed to. |
| $G{ErrorName} = 'Your Name'; |
| ErrorName |
The name to use for any error email messages. |
| $G{ErrorSubject} = 'Warning! Master Recommend V3 Error!'; |
| ErrorSubject |
The subject line to use for any error email messages. |
| $G{ToAddy} = 'webmaster@example.com'; |
| ToAddy |
The email address where normal messages and reports are to be mailed to. |
| $G{ToName} = 'Your Name'; |
| ToName |
The name to use for any incoming normal email messages/reports. |
| $G{ToSubject} = 'MasterRecommend Report'; |
| ToSubject |
The subject line to use for any incoming normal email messages/reports. |
| $G{FromAddy} = 'webmaster@example.com'; |
| FromAddy |
The email address to use when sending mail. |
| $G{FromName} = 'Your Name'; |
| FromName |
The name to use when sending mail. |
| $G{UseFormUserInFromForFriends} = 'yes'; |
| UseFormUserInFromForFriends |
If you want the visitor's name and email address in the "From:" header line
of the email sent to friends, instead of your own name and email address,
put "yes" here (with or without the quotes); otherwise, leave it blank
or put "no".
If you use your own name and email address, the form user's name and email
address will be in the "Reply-To:" header line.
If you use the form user's name and email address, there will be no "Reply-To:" header line.
This applies only to email sent to the visitor's friends. |
|
$G{AuthorizedDomains} = 'http://www.example.com, http://example.com';
|
| AuthorizedDomains |
A list of domain URLs which are authorized to use the program. Every webpage whose URL begins with one on the list can use the program. The URLs on the list are comma separated and on one line.
List all variations which people might use in their browsers, such as
- http://www.example.com
- http://example.com
(Note: To disable all domain restrictions, place a # character in front of the line. To re-enable, delete the character.)
To restrict use to a specific webpage within a domain, use the complete URL, e.g., http://willmaster.com/master/index.html |
$G{WeekdayNames} = 'Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday';
$G{LongMonthNames}='January,February,March,April,May,June,July,August,September,October,November,December';
$G{AbbreviatedMonths} = 'Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec';
|
WeekdayNames
LongMonthNames
AbbreviatedMonths |
As implied, these three items are
- a list of weekday names,
- a list of month names, and
- a list of abbreviated month names.
You may customize the spelling of the above to accommodate the written language
of your preference. (If your language has no month name abbreviations, then the list
of abbreviated month names should be the same as the completely spelled out month names.)
Each list is all on one line, the items separated with a comma. |
| $G{DateFormat} = 'Long'; |
| DateFormat |
Specify a date format from the following list. If no format is specified, the format will default to "Long".
| Format |
Translation
(assuming month=June day=8 year=2002) |
| USshort2 | 6/8/02 |
| USshort2Full | 06/08/02 |
| USshort4 | 6/8/2002 |
| USshort4Full | 06/08/2002 |
| UKshort2 | 8/6/02 |
| UKshort2Full | 08/06/02 |
| UKshort4 | 8/6/2002 |
| UKshort4Full | 08/06/2002 |
| Military2 | 8 JUN 02 |
| Military2LC | 8 Jun 02 |
| Military2Full | 08 JUN 02 |
| Military2FullLC | 08 Jun 02 |
| Military4 | 8 JUN 2002 |
| Military4LC | 8 Jun 2002 |
| Military4Full | 08 JUN 2002 |
| Military4FullLC | 08 Jun 2002 |
| MilitaryLong | 8 June 2002 |
| MilitaryLongFull | 08 June 2002 |
| Short | Jun 8, 2002 |
| Long | June 8, 2002 |
| VeryLong | Saturday, June 8, 2002 |
| NoYear | June 8 |
|
| $G{FormContainsMessageField} = 'yes'; |
| FormContainsMessageField |
If your form will not have a place for the site visitor to write a message to the friend, specify 'no' here. If your form will have a place for a message, specify 'yes'
The reason to specify 'no' is so the script won't process a message in case spammers make their own form with a message field. The reason to specify 'yes' if you have a message field on your own form is so Master Recommend V3 will accept it.
|
| $G{SecurityCookieDomain} = '.example.com'; |
| SecurityCookieDomain |
The security cookie is designed to prevent automated submission of the recommend form by spammer's or cracker's programs.
If you do not want to use this feature, remove everything from between the two single quote characters.
However, if you do want to use the security cookie, you'll need to specify your domain name between the single quotes. Specify your domain name preceeded with a period. Example:
'.example.com'
(The exact same specification must be made in the JavaScript on the web page with the recommend form.)
See The Form Security Cookie System for more information.
|
| $G{SecurityCookieDatabase} = 'securitydatafile'; |
| SecurityCookieDatabase |
To prevent the same cookie from being used over and over again by a spammer or cracker, a file keeps track of which cookies have been used during the last five days. This is done in a database file on the server.
Specify the name and location of the database file.
If you want the database to be in the same directory as the MasterRecommendV3.cgi script, then specify only its name. Otherwise, specify the directory location, too. Here are two examples:
'securitydatafile'
'data/securitydatafile'
The second example tells the script the file is to be in the "data" subdirectory (a subdirectory of where the script is installed) and it's name shall be "securitydatafile" (note that the script might or might not append a file name extension to the name you specify).
If the file shall be in a subdirectory, the subdirectory must allow scripts to create and update files. Try permissions 755 first, for the directory. If that doesn't work, then permissions 766, and if needed try 777.
Some servers allow scripts to create and update files in the same directory where the script is running. If yours does not, then the database file must be in a subdirectory.
|
[TOP OF PAGE]
Use a word processor which edits and saves text in ASCII/plain text format when making changes. NotePad, BBEdit Lite, and Pico all work fine.
The templates may be customized to accomodate the written language of your preference; just like the weekday and month names in the configuration file.
When downloaded from the http://willmaster.com/master/ web site, the email templates file was named emailtemplate.txt — one file containing three email templates.
The simplest installation is one email templates file. However, each "recommend me" webpage form can reference a different templates file, if you wish. This allows you to have unique outgoing emails for every section/product on your website. You can even have forms on other websites so long as the template files they reference are located on the same server with Master Recommend V3.
Each templates file contains templates for three emails:
- The email sent to your site visitor (optional).
- The email sent to your visitor's friend, the person your website is being recommended to.
- The email to the maintainer (yourself) telling you your website was recommended.
Each template must be in its own section in the file. Each has a beginning tag and an ending tag. Each begin/end tag must be ON A LINE BY ITSELF. (For convenience, the person to whom your website was recommended is called "friend.")
Here are the begin/end tags (the brackets are part of the tags):
| Template | Begin Tag | End Tag |
| Visitor's email | [VISITORMAIL] | [/VISITORMAIL] |
| Friend's email | [FRIENDMAIL] | [/FRIENDMAIL] |
| Maintainer's email | [MAINTAINERMAIL] | [/MAINTAINERMAIL] |
Master Recommend V3 ignores everything outside the begin/end blocks. You can
type notes to yourself in those places.
Immediately following each begin tag is another tag, [SUBJECT]
After the subject tag, on the same line, is the actual subject that will appear in the header of the outgoing email.
The line following the subject is where the body text of the email begins. The body text continues until the corresponding end tag is found on a line by itself.
Where the visitor's name, friend's email address, and other changeable data would go, Master Recommend V3 expects to find specific codes. The code is then replaced with the real data before the email is sent.
Where you want
this data to appear: |
Type this code
(including the brackets): |
| visitor's name | [visitorname] |
| visitor's email address | [visitormail] |
| friend's name | [friendname] |
| friend's email address | [friendmail] |
| the name of your site | [sitename] |
| the URL of your site | [siteurl] |
| the IP address of your visitor | [ip] |
| the referrer (the URL of the page with the form) | [ref] |
| date of recommendation | [date] |
| time of recommendation | [time] |
The above codes can be used in both the subject and body of the email templates.
Except for the date and time of the recommendation (which Master Recommend V3 provides automatically) the data in the above table is always provided by the "recommend me" webpage form. Thus, if all you are changing between different portions of your website is the name and URL, then you won't need a different email template. Just specify the name and URL as hidden fields of your form.
The visitor may or may not write a message for the person she/he recommends your site to. Because that is a variable situation, we use the following codes: [ifmessage] and [/ifmessage] And, where you would want the message to appear, use the code [message]
To reiterate, in case there is a message available:
| Where you want this effect: |
Type this code
(including the brackets): |
| begin message conditional block | [ifmessage] |
| end message conditional block | [/ifmessage] |
| include the message here | [message] |
Using a begin/end message block allows you to type text in addition to the visitor's message which will be included in the outgoing email only when a message is actually available (whether or not you include the message itself).
Examples for your study are the actual templates in the file emailtemplate.txt If you no longer have that file or the templates no longer serve as examples, you can get another copy from http://www.willmaster.com/master/recommend/
[TOP OF PAGE]
You have the script MasterRecommendV3.cgi and one or more email templates files ready for uploading.
The MasterRecommendV3.cgi script must be uploaded into a directory that is authorized to run CGI programs.
The email templates are not required to be in the same directory, but it is recommended that they are. Having the email templates files in the same directory as the script means whoever makes the "recommend me" webpage forms only needs to know the name of the templates file and not also the entire directory path to it.
However you decide to do it, upload the files to your server. Upload them as ASCII/plain text
Once they're uploaded, the MasterRecommendV3.cgi script needs to have permissions set to 755.
Some FTP programs, such as WS_FTP LE and CUTE FTP (both can be downloaded from http://www.tucows.com/), allow you to set permissions while connected to your server. If your host lets you have telnet access, you can set permissions that way.
If using one of the above FTP programs to set permissions, set the following:
| Owner: | read-write-execute |
| Group: | read-execute |
| Other: | read-execute |
If using telnet, change directories to where MasterRecommendV3.cgi is located and type the following:
chmod 755 MasterRecommendV3.cgi
[TOP OF PAGE]
The form's method and its action are both specified in the form tag <form...
The form's method must be "POST" and it's action must be the URL to the MasterRecommendV3.cgi script. The URL can be a relative URL such as
/cgi-bin/master/MasterRecommendV3.cgi
or it can be a complete http URL such as
http://example.com/cgi-bin/MasterRecommendV3.cgi
Example forms are included in the ZIPped download file.
Master Recommend V3 is designed to allow different types of forms. The names and email addresses of the respective parties are required. The form may also, optionally, provide a text area for the visitor's message to the friend. It may also allow the visitor to request a copy of what is sent to the friend.
The following tables list all possible "recommend me" webpage form fields for Master Recommend V3. It specifies whether or not the field is in a hidden form tag. And it specifies whether it is a required field or optional.
| The name or title of your site |
| name: sitename | hidden: yes | Required |
| The URL of your site |
| name: siteurl | hidden: yes | Required |
| The name of file containing the email template |
| name: template | hidden: yes | Required |
| Note: |
|
If the email templates file is not in the same directory with MasterRecommendV3.cgi, then the name of the file must include the complete directory path to the file. |
|
| Is the visitor getting an acknowledgment/thank you for the recommending your site? (use"yes" or "no") |
| name: visitorgetsmail | hidden: yes | Optional |
| The URL where the visitor is sent to after completing the form |
| name: redirecturl | hidden: yes | Optional |
| The visitor's name |
| name: visitorname | hidden: no | Required |
| The visitor's email address |
| name: visitormail | hidden: no | Required |
| The friend's name |
| name: friendname | hidden: no | Required |
| The friend's email address |
| name: friendmail | hidden: no | Required |
| A text area for the visitor to type a message to the friend your website is being recommended to. |
| name: message | hidden: no | Optional |
| A checkbox for the visitor to click if s/he wants to receive a copy of the email sent to the friend. |
| name: sendcopy | hidden: no | Optional |
|
The form, of course, must have a "submit" button. And it must end with </form>
Examples of several different types of forms are included in the ZIPped download file. You may modify page style and format.
[TOP OF PAGE]
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.
Four steps are required to implement the Form Security Cookie System for Master Recommend V3
-
The FORM tag must contain name="MasterRecommendForm" attribute.
-
The form must contain a hidden field name="sc"
-
Specialized JavaScript below the form must specify the domain name.
-
Master Recommend V3 must specify the domain name.
Example forms are included in the download ZIP file. Several of the examples implement the Form Security Cookie System.
Master Recommend V3 has instructions and examples within the script itself.
This is how the Form Security Cookie System works:
-
When the form is loaded into the user's browser, JavaScript determines a unique value for a cookie. It then:
-
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.)
-
Stores the cookie value in the form's hidden field name="sc"
-
When the form is submitted, the cookie's value is submitted to Master Recommend V3 along with the rest of the form values.
-
If Master Recommend V3 has been told to validate the security cookie, which is done by specifying the domain name in the Perl script itself, it then:
-
Verifies that a security cookie exists and that its value matches what arrived in the form's hidden field name="sc"
-
Verifies that the same security cookie has not previously been used. (Master Recommend V3 looks back five days.)
-
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 V3 both reside on the same domain. If you wish to have recommend forms on other domains, Master Recommend V3 must be installed on those domains.
[TOP OF PAGE]
Test your new installation before you go live with it. (After a few embarrassments, you learn that rule well. No matter how simple the project, something can go wrong.)
Upload your Master Recommend V3 program. Make a "recommend me" form. Upload the webpage with the form for testing.
Verified it works okay before linking to the page with the form.
Things that can go wrong and what to do about it:
| "You are not authorized to access this script" or "Forbidden" type of error is encountered when the form is used |
The file permissions for MasterRecommendV3.cgi are incorrect.
or
The directory where MasterRecommendV3.cgi resides is not authorized to run CGI scripts |
| "Internal Server Error" type of error when the form is used |
A list of some common reasons for the Internal Server Error are addressed at
http://willmaster.com/support/faq/
|
| When the form's submit button is clicked, a "File not found" or similar error comes up.
|
The
action="______" attribute of the <form... tag does not contain the correct URL to your copy of MasterRecommendV3.cgi |
| The form seems to work correctly but no mail arrives |
The value of $G{MailProgram} = '_______'; in your script MasterRecommendV3.cgi does not reflect the location and name of your server's mailer, or does not contain required flags.
or
Any of a number of other reasons, some of which are addressed at http://willmaster.com/support/howtoinfo/emaildebugarticle.shtml
|
[TOP OF PAGE]
We have made Master Recommend V3 as easy to install as we could. If you still need help, we offer installation service.
Please see http://willmaster.com/master/installation.shtml for further information.
[TOP OF PAGE]
Put your privacy statement, or a link to it, in plain site next to your "recommend me" webpage form.
Wherever you put your "recommend me" form, put a link to it on every page of your website. Place the link where it is plainly visible (without being obnoxious about it) at every point where your visitor might decide your site is worth recommending.
An article called "Let Your Visitors Recommend Your Website" was printed in WillMaster Possibilities and is available at http://willmaster.com/possibilities/archives/.
[TOP OF PAGE]
New Master Series programs are released every once in a
while. Others are upgraded. Master Recommend V3, itself, will
probably be enhanced from time to time.
The best way to ensure you hear about it when it happens is to
subscribe to the free weekly WillMaster Possibilities ezine.
Every week, WillMaster Possibilities delivers something new
for your website to do. Things you've heard about; once in
a while something brand new; and sometimes a prize that has
been around for a long time, presented in a different way.
The idea is to offer you possibilities to make your website active.
WillMaster Possibilities is about things you can do yourself.
Because the editor and the programmer are the same person,
WillMaster Possibilities is where new and upgraded Master Series
scripts are announced first.
To get your free subscription started, stop by the
http://willmaster.com/possibilities/ where you'll find a form and some back issues.
|