Feedback README - August, 1996

OUTLINE


Modifying Feedback.cgi

VARIABLES IN PERL SCRIPT

Must Be Modified!

The following variables appear in the source of Feedback.cgi. You will need to use a text editor when making changes to the following variables contained in the source code.
$MAIL_PROG
This variable must define the location to your server's sendmail program. If this is incorrect, form results will not be mailed to you. To determine the location of this program on a unix machine, try using one of the following commands and copying the resulting location:

% which sendmail

% whereis sendmail

$FLAGS
This variable is used to specify which flags should be used on the command line right after the $MAIL_PROG variable. This is so that Feedback can be compatible more easily with other programs besides sendmail. Set the $FLAGS variable so it tells whatever mail program you use to accept input after you hit return. For sendmail, set $FLAGS = "-t";.

$LOCK_DIR
This specifies the directory where your lock files will be stored if your system doesn't support flock.

$MAX_WAIT
$MAX_WAIT defines how long the script will wait and try to get the the lock file privileges before overriding them and assuming the lock file is false. 3 or 4 seconds should be enough.

$MAX_TRIES
$MAX_TRIES defines how many times the lock routine will cycle through if it can't get a lock before returning an error to the user.

$README
This variable inside of the Feedback script is a URL pointing to the location of this document, the README.html that comes with Feedback. This link is then returned to users when they get an error setting up their form to work with Feedback, offering them a way to find out more about Feedback configuration fields and syntax.

Variables in FeedbackAdmin.cgi

$ENCRYPT
This variable should be set to 1 if you are on a unix system supporting encrypt(). Otherwise, set it to 0 and your password will contain a plain text username and password. You can read more about changing this in the $PASSWD_FILE description.

Placing Feedback on Your System

Uploading Feedback from your computer to your server
Many users who use Feedback and have to edit the source to change the variables will do so on their local computer which is often a Mac or PC. These operating systems have a tendency to attach control M (^M) characters to the end of each line. If you do edit Feedback on a Mac or PC and plan on uploading it to a Unix server, make sure that you upload it in ASCII mode or Feedback will generate errors causing your script to malfunction.

Placing Feedback in your CGI-BIN
If you have access to a cgi-bin on your system, simply place Feedback.cgi into your cgi-bin, chmod it 755 and then begin writing your Forms, keeping in mind the Fields Designated Special.

chmod 755 Feedback.cgi
Once Feedback is on your system, you will have to make it executable by users of the web and yourself. To do this, if you are on a unix system, type:
	chmod 755 Feedback.cgi
or if you renamed it to Feedback.cgi substitute that in for Feedback.cgi above.

NOTE: You will also need to execute the same command for FeedbackAdmin.cgi or FeedbackAdmin.cgi.

chmod 777 feedback.html
Once you have established the location of $FEEDBACK_FILE, you will need to execute the following command so that the feedback file will be writable by the web server:
	chmod 777 feedback.html
If you choose to rename your feedback.html file to another name, simply put that in the above command in place of feedback.html.

Hidden Feedback Entry Form Field.

config_file
The config_file is the only hidden for field that you will need in your feedback entry page for the script to work. This variable will point to the config.txt file (or whatever you wish to call it) so that the Feedback program will know where to look for all of the configuration variables for that feedback. This allows multiple users on the same system to run off of the same feedback script with just a different config file in their home directory. The value of the config_file form field should be set to the full path of your configuration file. If you name your configuration file config.txt and place it on your server in the /home/username/public_html/ directory, then you would set the form field to:

<input type=hidden name="config_file" value="/home/username/public_html/config.txt">

Once this form field is set inside of your feedback entry form, you can then create your entry form to contain any fields you wish and look however you want. Just make sure if you don't use the pre-made templates that come with the Feedback script, that you learn how to create your own templates in the Using Templates section.

Configuration File

The configuration file is necessary if you wish to have an operable feedback. The configuration file will be used as an include file and all of the variables that are needed for the feedback must be defined in the configuration file. Any of the variables in bold face above their description MUST appear in your configuration file. The others are optional, and you may wish to use them to customize the look and operations of your feedback program.

Variables in Configuration File

Any of the configuration fields in bold are required in order for the feedback to correctly operate. Keep in mind that the '$' and '@' characters must be kept at the beginning of variable names in your configuration file as your configuration file will simply be read in and used for the variables as-is.

Basic Feedback File Locations

$FEEDBACK_FILE
The $FEEDBACK_FILE variable defines the location of your feedback.html file or whatever you have chosen to name your feedback file which contains the entries. It is required for your feedback to work correctly, as without it, the feedback would be virtually worthless. Inside of the $FEEDBACK_FILE you can have it look however you want. The one required line you include in the source of this file is:

This is so the feedback.cgi program will be able to identify where to start placing the newest entries for your feedback. If your feedback.html file was located in /home/username/public_html/feedback/, this variable would be defined in the config_file as:

$FEEDBACK_FILE = '/home/username/public_html/feedback/feedback.html';

This file must be chmoded 777 so that it can be written to by the web server.

$FEEDBACK_NUM
The $FEEDBACK_NUM variable is required and defined the location of the file which will hold the current entry number. This entry number is used for a variety of purposes, most often administrative. Without this $FEEDBACK_NUM file, your Feedback program will not function. You do not even need to create this file, however the directory that contains this file must be chmoded 777 or you can create this file with a '0' in it and chmod it to 777. If you named this file num.txt and placed it in the /home/username/public_html/feedback/ directory, the value for this variable would be:

$FEEDBACK_NUM = '/home/username/public_html/feedback/num.txt';

Defining Feedback Entry Order

$ENTRY_ORDER
By default, the feedback program will add the newest entries to the top of your feedback. This is so every entry is at the top at least once, rather than having to constantly scroll through old entries to get to the newest entries as other feedbacks do. If you wish to use this default action, you can simply leave your $ENTRY_ORDER variable as:

$ENTRY_ORDER = '';

Otherwise, if you wish to have the oldest entries appear at the top and any newer entries at the bottom, simply set your $ENTRY_ORDER variable to:

$ENTRY_ORDER = 'oldest->newest';

Limiting HTML Usage in Feedback Entries

@LIMIT_HTML
Do you want to allow HTML, but are sick of your users adding <blink> tags or <img> tags all over their entries? The @LIMIT_HTML array may hold the solution for you. Add any tag you wish to ban from your feedback to this array and the Feedback script will automatically throw it out. For instance, if you wanted to ban any <h1>, <img>, or <blink> tags from your feedback, your @LIMIT_HTML array would look like:

@LIMIT_HTML = ('h1','img','blink');

If you want ALL HTML tags users enter in their entries to be removed, simply set @LIMIT_HTML to:

@LIMIT_HTML = ('all');

Or if you don't care what HTML tags your users use, simple set @LIMIT_HTML to:

@LIMIT_HTML = ('');

Getting Rid of Bad Words in Feedback Entries Bad words have plagued feedbacks over time by users who use them casually or wish to cuss you out to eternity. This Feedback script has a solution for this. You can now specify a file which contains a list of bad words which should be removed from all entries or cause an entry to be rejected.
$BAD_WORD_FILE
The $BAD_WORD_FILE variable specifies the location of the file containing the list of bad words. The bad words in this file should be one per line, so that the script can separate each word and look through the entries weeding them out or rejecting the post. If your bad word file was called badwords.txt, as it is in the distribution, and you placed this in /home/username/public_html/feedback/, your $BAD_WORD_FILE variable would be:

$BAD_WORD_FILE = '/home/username/public_html/feedback/badwords.txt';

@BAD_WORD_FIELDS
As a default, the Feedback script will check all fields for bad words. But, if you only really wanted to check a couple fields to make sure no bad words were there, you can use the @BAD_WORD_FIELDS array to do so. For instance, if you have Comments and Feedback fields named 'comment' and 'feedback' in the source, and these were the only fields you were really worried about containing bad words, you would set the @BAD_WORD_FIELDS array to:

@BAD_WORD_FIELDS = ('comments','feedback');

Otherwise, if this is not defined and $BAD_WORD_FILE is, all fields will be searched for bad words, and you can leave this array as:

@BAD_WORD_FIELDS = ('');

$BAD_WORD_ACTION
By default, if the feedback script finds a bad word in the posting, it will simply remove it and post the entry as it normally would, without the bad word(s). You also have the option of rejecting the post completely if the entry contains any of the bad words. To do this, set the $BAD_WORD_ACTION variable to 'reject', like:

$BAD_WORD_ACTION = 'reject';

If you just want to keep the default way of removing the bad words and posting the entry, leave $BAD_WORD_ACTION undefined:

$BAD_WORD_ACTION = '';

Rejecting Duplicate Entries and Banned Hosts

The following options to the feedback are not required, and are simply useful if you wish to reject duplicate entries entered right in a row or wish to reject postings from a certain host who continues to post entries you don't like to your feedback.
$LAST_LOG_FILE
If you wish to use the feature which will attempt to reject duplicate entries, the $LAST_LOG_FILE variable must contain the path to the log file which will have a listing of those users who have most recently added an entry to your feedback. This file must also be writable by the web server, which means you need to chmod it to 777. If you named this file lastlog.txt and placed it in /home/username/public_html/feedback/, the $LAST_LOG_FILE variable would look like:

$LAST_LOG_FILE = '/home/username/public_html/feedback/lastlog.txt';

$LAST_LOG_MAX
By default, this value is set to 3 entries. The $LAST_LOG_MAX variable specifies how many entries the Feedback script should g back in order to see if this is a duplicate entry. The Feedback decides it is a duplicate entry if the REMOTE_HOST and REMOTE_ADDR environment variables match up. If they do, then it rejects the post. That means you shouldn't set this value too high or you may be rejecting valid posts which are coming from the same IP address, just with a different user. If your feedback gets extremely heavy usage, you may wish to set this variable slightly higher than 3, but it's main purpose is just so that people who hit submit twice don't have their entry appear again in the feedback. To set this variable so that the last 5 entries are checked, you would do:

$LAST_LOG_MAX = '5';

Or for a default of 3, leave it at:

$LAST_LOG_MAX = '3';

$BANNED_HOSTS_FILE
The $BANNED_HOSTS_FILE is another way to ban a person from ever adding another entry to the feedback. It actually bans anyone from their host or IP address, which I guess is better than having one person from that site repeatedly messing up your feedback. This variable should hold the pathname to the file which contains the banned hosts. If you name your file banhosts.txt and place it in /home/username/public_html/feedback/, then your variable should look like:

$BANNED_HOSTS_FILE = '/home/username/public_html/feedback/banhosts.txt'

You should not edit this file by hand as the IP addresses and host names are configured in here in a way that is easy for the script to tell them apart and if you reverse them or do not use the correct separators, the script may not catch the banned user. Instead use the administrative functions to ban a user. The remove, approve and archive functions of the FeedbackAdmin program allow you to ban the user.

Using Templates to Define Feedback Appearance

Templates are probably the best addition to this Feedback program. They allow you to create a custom feedback program with custom designed interfaces and entry templates allowing you to integrate this feedback into your site, and take away the same old feedback appearance. Default templates do come with the script however if you aren't very creative or wish to just set up something simple for any visitors to your site. You can read more about using templates in the book or FormMail README file.
$FEEDBACK_ENTRY_TEMPLATE
This is the only required template, as no default entry will be added inside of the script. If you choose to use the default setup, however, you can simply use the default templates and everything will actually be very easy to set up. Otherwise, using the field names you have customized in the addguest.html or whatever file the add form is on, you can create a custom looking template. Let's say that you had an entry form which look like:

Name:
E-Mail:
URL:
Title:

The source might look like:

Name: <input type=text name="name" size=30><br>
E-Mail: <input type=text name="email" size=30><br>
URL: <input type=text name="url" size=40><br>
Title: <input type=text name="title" size=40><br>
<input type=hidden name="config_file" value="/path/to/config.txt">

If all you wanted the feedback entry to look like was:

title
name


Which has a source of:

<a href="url">title</a><br>
<a href="mailto:email">name</a>
<hr>

Your feedback_entry_template would look something like this:

<a href="<<url>>"><<title>></a><br>
<a href="mailto:<<email>>"><<name>></a>
<hr>

Then if you saved this file as entry.txt in the /home/username/public_html/feedback/ directory, the variable configuration might look like:

$FEEDBACK_ENTRY_TEMPLATE = '/home/username/public_html/feedback/entry.txt';

$SUCCESS_TEMPLATE
The $SUCCESS_TEMPLATE contains the path to the template to be used once an entry has been added. This template will be parsed and then returned to the user as the HTML confirmation page. This allows you to tailor the response page to fit your feedback options and the style of your web pages. If you do not use this variable or the $REDIRECT variable, a generic response, using the $FEEDBACK_ENTRY_TEMPLATE, will be sent back to the browser. If you wish to use this option and have your success_html_template in the success.txt file in the /home/username/public_html/feedback/, you would set this variable to:

$SUCCESS_TEMPLATE = '/home/username/public_html/feedback/success.txt';

$ERROR_TEMPLATE
The $ERROR_TEMPLATE variable defines the location to the template which will be brought up should the user forget to fill in all of the fields specified in @REQUIRED. This allows you to create custom error messages. If your error template file was named error.txt and placed in the /home/username/public_html/feedback/ directory, your variable setup would look like:

$ERROR_TEMPLATE = '/home/username/public_html/feedback/error.txt';

$PREVIEW_TEMPLATE
The $PREVIEW_TEMPLATE allows you to create a custom previewing page for users to make sure thir entry looks exactly right before they finally approve to submit it to the feedback. If this file was named preview.txt and placed in the /home/username/public_html/feedback/ directory, the variable configuration for this would be:

$PREVIEW_TEMPLATE = '/home/username/public_html/feedback/preview.txt';

NOTE: In your preview page you MUST reprint the form with hidden fields. The script will not keep track of that for you!!! In other words, if we take the example from $SUCCESS_TEMPLATE, and were to create a preview function out of that, we would place the following line in the original script:

<input type=checkbox name="preview" value="YES"> Preview Entry

Or if you don't want to give users a choice and automatically make them preview:

<input type=hidden name="preview" value="YES">

Then your preview.txt (preview html template) might look similar to:

<html><head><title>Preview Feedback Entry</title></head><br>
<body><center><h1>Preview Feedback Entry</h1></center><p>

Please Preview Your Entry Below. If it is correct, hit the 'Add Entry' button below.<p><hr><p>

<a href="<<url>>"><<title>></a><br>
<a href="mailto:<<email>>"><<name>></a>
<p><hr><p>
<form ...>
<input type=hidden name="name" value="<<name>>"><br>
<input type=hidden name="email" value="<<email>>"><br>
<input type=hidden name="url" value="<<url>>"><br>
<input type=hidden name="title" value="<<title>>"><br>
<input type=hidden name="config_file" value="/path/to/config.txt"><br>
<input type=submit value="Add Entry"><br>
</form>

The above example shows how to recreate the form in hidden fields so that the user doesn't see it, as well as show them a demonstration of what the entry will look like. Make sure you include all of the fields you had in your form in your preview.txt file, except the preview field, as including it would cause the user to see another preview field. :-)

$REDIRECT
The $REDIRECT variable is used to redirect the user to a pre-made HTML file as their successful entry addition message. This variable will be used if it is filled in and bypass the success_html_template and the generic response. If you have a page at: http://your.host.xxx/~username/feedback/success.html that you want the user to see if they add an entry, simply define your variable as:

$REDIRECT = 'http://your.host.xxx/~username/feedback/success.html';

Requiring Feedback Entry Fields to be Filled In

@REQUIRED
If you wish to have certain form fields required, so that users entries are not posted unless they are all filled in, you can use the @REQUIRED form field. For instance, if you have the form fields: name, email, url and title, but you only want name and email to be required, you would set this variable up as:

@REQUIRED = ('name','email');

If these are not filled in, the script will return an error message, either generic or as specified in $ERROR_TEMPLATE.

Automatic & Manual Archiving of Feedback

A new feature of the feedback script is that it now allows automatic archiving by month or number of entries, as well as manual archiving through the $USE_ADMIN.

$ARCHIVE_TYPE
This variable specifies the type of archiving that should occur. If you plan to use automatic archiving, this variable must be set to the type you want. There are two options: month or num. The former will archive each entry by month. As the entries are added, they will be written to both the main feedback file and a monthly file. When a new month comes, the other entries in the feedback are taken out, and you are left with the archive by month file. If you wish to use the num feature, you get to set how many posts you wish to have on the main page. When that number of posts is reached, the posts will begin scrolling over to the file specified in $ARCHIVE_BY_NUM_FILE.

Archiving by Month:

$ARCHIVE_TYPE = 'month';

Archiving by Number:

$ARCHIVE_TYPE = 'num';

$ARCHIVE_MONTH_DIR
This field specifies what directory the monthly archive files should be written to. A generic feedback file will then appear when the first entry is added into the correct monthly feedback archive file. After these files have been created, you can feel free to edit them or change them as long as you leave the filenames the same and keep the <!--begin--> tag in the HTML source. If you want to keep all of the feedback archive files in the directory: /home/username/public_html/feedback/archive/, you would set this variable to:

$ARCHIVE_MONTH_DIR = '/home/username/public_html/feedback/archive/';

NOTE: Since these files will be created automatically by the web server, you must chmod 777 this directory.

$MAX_ENTRIES
If you choose to archive by number of entries, this variable MUST contain an integer value. The number this variable holds is how many messages your main feedback file will contain. For instance, if you only want 50 entries on the main page, and the rest to be placed in the $ARCHIVE_BY_NUM_FILE file as newer entries are added, you would set this variable to:

$MAX_ENTRIES = '50';

$ARCHIVE_BY_NUM_FILE
This is the file in which all of your old feedback entries that are over the $MAX_ENTRIES limit will be sent. If you create it, it must be chmoded to 777 so that the feedback program can write to it. It must also contain the <!--begin--> line so the script knows where to insert these entries. If this file is located at: /home/username/public_html/feedback/archive.html, you would set this variable to:

$ARCHIVE_BY_NUM_FILE = '/home/username/public_html/feedback/archive.html';

$MANUAL_ARCHIVE_FILE
This file location must be defined if you plan to use the manual archiving functions provided by the admin script. If so, set this value to the file you want to place all entries that you tell the administrative script to archive. If you create it, it must be chmoded to 777 so that the feedback program can write to it. It must also contain the <!--begin--> line so the script knows where to insert these entries. If this file is located at: /home/username/public_html/feedback/archive.html, you would set this variable to:

$MANUAL_ARCHIVE_FILE = '/home/username/public_html/feedback/archive.html';

Sending Reply Messages to Users

$REPLY_TEMPLATE
If you wish to send a reply message to the user who just filled in an entry for your feedback, simply define this variable and create an email template for the body of the response message. The remote user's email address will be checked before hand to make sure it is not an obviously bad email address.

If this file was located in /home/username/public_html/feedback/reply.txt, your variable would look like:

$REPLY_TEMPLATE = '/home/username/public_html/feedback/reply.txt';

$REPLY_FROM
In this variable you should define your e-mail address or the address you want the auto-replies to be sent from. For example if your name is John Doe and your e-mail is john@doe.com, you could set this variable to:

$REPLY_FROM = "John Doe ";
$REPLY_FROM = "john@doe.com (John Doe)";
or simply:
$REPLY_FROM = "john@doe.com";

This allows the remote user to be able to reply to you.

$REPLY_SUBJECT
This variable allows you to set the subject of the auto-reply email message. So if you wanted to have a subject in the reply message of "Thanks for signing my feedback." you would set this variable to:

$reply_to = "Thanks for signing my feedback";

Sending Yourself E-Mail When Entry is Added

$EMAIL_TEMPLATE
You can also send a message to yourself every time the feedback is signed. If you wish to do this, create an email template with the body of the message in it, and then fill in the $EMAIL_TO and $EMAIL_SUBJECT variables. For more information on templates, see Using Templates.

If you were to store your email_template at: /home/username/public_html/feedback/email.txt, set this variable to:

$EMAIL_TEMPLATE = '/home/username/public_html/feedback/email.txt';

$EMAIL_TO
This tells the script the email address of whom to mail this file to. So if your email address is john@doe.com, you would set this variable to:

$EMAIL_TO = "john@doe.com";

$EMAIL_SUBJECT
This variable specifies the subject of the e-mail message you will receive. If you wanted this to be "Someone signed the feedback.", you would set this variable to:

$EMAIL_SUBJECT = "Someone signed the feedback.";

$EMAIL_FROM
Most likely you will want the from address to be the user's e-mail they specified. But should you wish to change this for any reason, simply put an e-mail address in here and all of the email messages will be sent as if they were from that address.

Using the Administrative Features of Feedback

If you wish to use the administrative features of the feedback program, several of the variables below must be filled in. There is also another IMPORTANT step you must take, which is editing the default admin.html that comes with the scripts. You will need to change the action="" of the form to point to your $ADMIN_CGI_URL and change the default config_file path to the correct config_file path. Otherwise, the admin functions may not work.

$USE_ADMIN
If you want to use the administrative features of the feedback script, set this to 'YES':

$USE_ADMIN = 'YES';

$use_password
By default this is set to 'YES'. If you wish not to have to type your password and username into the form for FeedbackAdmin, you can change this to something other than YES, and it will not be required. We do recommend you use it however, as otherwise people could mess with your feedback.

$PASSWD_FILE
This file contains the username and password for your site. At first, this is set to Username: 'Guest' and Password: 'Admin' encrypted. Those are case sensitive. Should your machine not support encryption, you must change these to plain text and have the password file look like: "Guest:Admin" without the quotes. That is all that needs to be in thein the passwd_file. Then, you need to reference the full path to this file in your $PASSWD_FILE variable, like:

$PASSWD_FILE = "/path/to/passwd.txt";

$APPROVE_FILE
If you have this variable set, the feedback script will assume you want to approve all entries before they are added to the feedback. Any entries will then do to this file and wait for you to approve them through the FeedbackAdmin script before they are posted into public view on your web site. So simply create a file with nothing in it, chmod it to 777, and then point this variable to it. You will then be able to approve files through the FeedbackAdmin script. If this file is kept in /home/username/public_html/feedback/approve.txt, set this variable to:

$APPROVE_FILE = '/home/username/public_html/feedback/approve.txt';

If you do not want to use the approve function, make sure this variable stays undefined:

$APPROVE_FILE = '';

$ADMIN_CGI_URL
This is the URL to your FeedbackAdmin.cgi or FeedbackAdmin.cgi file. It will be used in the creation of your forms so that the files are pointed at your correct scripts. If you plan to use the administrative function, this must be set correctly. If you keep this file at: http://your.host.xxx/cgi-bin/FeedbackAdmin.cgi, set this variable to:

$ADMIN_CGI_URL = 'http://your.host.xxx/cgi-bin/FeedbackAdmin.cgi';

$ADMIN_URL
This is the URL to your administrative HTML starting page (usually admin.html) If this page is located at: http://your.host.xxx/~username/feedback/admin.html, set this variable to:

$ADMIN_URL = 'http://your.host.xxx/~username/feedback/admin.html';

Modifying Default Distribution

addentry.html
There are two things that must be modified inside of this file. First, you must modify the action="" of the <form> tag to point to your feedback.cgi script, rather than the fake script it is currently pointing at. You must also change the <input type=hidden name="config_file" value="..."> field to point to your config_file.

Keep in mind, that with the new template features of the feedback script, there is no reason for you to HAVE to keep the default distribution. You can create your own addition forms and just make the feedback work with them by editing the default entry.txt template.

feedback.html
The feedback.html file can be left as-is if you use all of the default setup, however you will need to chmod this to 777.