Overview:

The dynamic nature of the Web is often overwhelming to those who aren’t used to receiving immediate feedback from their audience. To anyone with a little marketing savvy, however, it becomes an invaluable asset. Even if you aren’t running a business-oriented site, you can gain tremendous insight into what makes your site effective and what can make it more effective by offering your visitors a chance to provide you with feedback. You can also use this feedback as an endorsement for your site or as a forum to allow visitors an opportunity to make themselves heard. Feedback consists of two programs that work together to allow you to collect and manage feedback from visitors to your site in such a manner.

Features:

Feedback’s features primarily dictate how the visitor’s feedback message will be processed when it is submitted.

Customized Look and Feel
Feedback allows you to use template files to make sure the forms and pages generated by the program match the look and feel of the rest of your site.

	Automatic or Manual Message Posting You can configure Feedback to post messages to a display page automatically or manually using FeedbackAdmin.
	Automatic Message Archiving You can configure Feedback to automatically archive messages by month or according to the number of messages in your feedback page.
	Obscenity and HTML Filter Option You can configure Feedback to automatically remove obscene or inappropriate language (you define what’s acceptable and what isn’t) and specified (or all) HTML markup tags from incoming messages or to simply reject messages that contain such language.
	Message Preview Option Feedback includes the option of giving visitors a preview of their message before submitting it.
	Automatic Email Reply to Visitors Feedback can automatically send a customized email message to a visitor after they submit a feedback message.
	Automatic Email Notification to Administrator Feedback can also send a customized email message to the administrator of the feedback form each time a message is submitted using the form.
	Ability to Specify Required Fields Feedback gives you the ability to specify that some or all of the fields in a feedback form must be filled in before the form input will be accepted by the program.
	Multiple Form Support You can use configuration files to have the same copy of Feedback handle multiple feedback forms for different sites.
	Duplicate Entry Removal Visitors are often impatient when using a form and will press the Submit button more than once if the system doesn’t respond fast enough. Feedback includes the option to ignore multiple posts from the same visitor.

FeedbackAdmin's features allow you to manipulate messages after they have been submitted.

	Manual Message Approval, Removal and Archiving Feedback contains options to require administrative approval before messages are posted to the public feedback file. Any entries you do not wish to post or wish to remove from your feedback file can also be taken out through the use of FeedbackAdmin. Manual archiving of messages is also done through this program.
	Ability to Ban Specific Visitors To avoid problems with repeated, inappropriate posts from specific visitors, FeedbackAdmin allows you to ban such visitors from using your feedback form.
	Optional Password Access FeedbackAdmin gives you the option of having to enter a username and password in order to gain access to the program, both of which can be modified from within the program.

Required Hidden 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 /dnshome/domain.com/etc/ directory, then you would set the form field to:

<input type=hidden name="config_file" value="/dnshome/domain.com/etc/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 red 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.

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
Variable:	Description:
$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 /dnshome/domain.com/htdocs/feedback/, this variable would be defined in the `config_file` as: `$FEEDBACK_FILE = '/dnshome/domain.com/htdocs/feedback/feedback.html';`
$FEEDBACK_NUM	The `$FEEDBACK_NUM` variable is required and defines 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, it will be done automatically. If you named this file num.txt and placed it in the /dnshome/domain.com/htdocs/feedback/ directory, the value for this variable would be: `$FEEDBACK_NUM = '/dnshome/domain.com/htdocs/feedback/num.txt';`

Defining Feedback Entry Order
Variable:	Description:
$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
Variable:	Description:
@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
Variable:	Description:
$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
Variable:	Description:
$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.

Requiring Feedback Entry Fields to be Filled In
Variable:	Description:
@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`.

Requiring Feedback Entry Fields to be Filled In
Variable:	Description:
$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
Variable:	Description:
$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
Variable:	Description:
$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_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.
$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";`

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.

Administrative Features
Variable:	Description:
$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 the&127;&127;&127;&127;&127;&127;&127;&127;in 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';`

$FEEDBACK_ENTRY_TEMPLATE

	$SUCCESS_TEMPLATE
	$ERROR_TEMPLATE
	$PREVIEW_TEMPLATE
	$REDIRECT

Modifying Default Distribution

	addentry.html
	feedback.html

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:

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:

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:

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

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.

Copyright:

This script is part of the CGI/Perl Cookbook by Craig Patchett and Matthew Wright. The script is only available to users who have bought the book. Esosoft Corporation has bought this book, however you are not able to copy the Feedback script from our cgi system directory to your file area or take it to another web hosting provider. You are only allowed to use the script if you are a customer of Esosoft!