Toronto Free-Net
  Front  •  Account  •  TFNews  •  Help  •  Contact  
Guestbook utility
The TFN Guestbook Utility provides a mechanism for processing a member-defined HTML form submission, converting it to an easily readable HTML table format of Field Names and Contents, and insert this information into a Guestbook Webpage, optionally e-mailing the information to the page owner as well.

Using the Guestbook Utilitiy is simple. You need to create THREE web pages all in the same directory:

All three pages can be coded to suit your own personal tastes in web page design and layout, as long as you include in each page the required pieces of HTML code, as explained below. You can use our Templates to help you create your guestbook, but we still recommend reading through these instructions before using them.

The first page is your actual Guestbook Web Page. In this web page you need to include the following line at the point where you want new form submissions inserted:

<!-- TFN GUESTBOOK INSERT AFTER THIS LINE -->

All in capitals, with single spaces between words.
There must be no empty space or other text on the line before the "<".
AFTER causes entries to be ordered newest first.
BEFORE causes entries to be ordered newest last.

Important: If this line is not in the HTML or not properly formatted, the Guestbook Utility will not update the page. This is a security feature to prevent unauthorized access to your files. You are granting limited access by including the above line in your page.

The second page is your Form Web Page, which may be created in any way or shape that you desire, as long as you use METHOD="GET" in your <FORM>. And keep in mind that ALL form fields will be added to your guestbook and/or mailed to you, and that the names you use for the 'NAME' attribute in your <INPUT> fields will be the Field Names that appear in the left column of your Guestbook (or E-mail). This page should have it's <FORM ACTION=...> point to your third page (your Thank You message).

The third page does the work of updating the guestbook, by including in its HTML a Server Side Include command to execute the TFN Guestbook Utility. The Utility formats the form data, inserts it into the guestbook and/or sends it as mail, then generates a simple text message thanking your visitor for submitting their information, and displays the submitted information in the same format as it will appear in the Guestbook/E-mail. Because it is an "Include", you can format the surrounding Thank You page to match the look of the rest of your website, with headers or footers as you desire.

Just add the following two lines of HTML code to the third web page in the location where you want the "Thank You" text to appear:

<!--#set var="GUESTBOOK" value="guestbook.html" -->
<!--#include virtual="/cgi-bin/tfnguestbook" -->

Where GUESTBOOK is in capitals, and 'guestbook.html' is the name you chose for your Guestbook web page. It can be anything you like as long as it is in the same directory as the Thank-You Web page and form.

Then change the permissions on the Thank-You web page containing these commands so that the OWNER 'execute' flag is enabled/turned-on. This enables SSI processing.

When a visitor enters a form, and clicks on submit, they will see your Thank-You web page with the following text appearing at the location in your page where you placed the 'include' command listed above:

    Thank you for your submission.

    The following information was submitted:

    Field-Name     Field contents
    Field-Name     Field contents.....

Additional Features/Options:

By using a few simple 'set' commands, you can control the appearance of the fields added to your Guestbook, keep a Text File copy of entries, and/or e-mail the submitted information. You can also control the 'Thank You' text displayed to the user.

Required Fields
If there are fields on your form that you do not want visitors to leave empty, list the field names, separated by commas in a line like this one, which you add to the Thank-You page BEFORE the 'include' command:

<!--#set var="REQUIRED" value="fieldname1,fieldname2,..." -->

Note that the word 'REQUIRED' is upper case. 'fieldnames' are the *exact* (including case) names used on your form, separated by commas, all enclosed in quotes (Don't make the mistake of trying to enclose each fieldname in its own quotes).

Guestbook Format - No Field Names
It may suit your purposes to have the form field contents appear in your Guestbook web page without the Field Names beside them. You can omit the names by adding the following line to the HTML code BEFORE the 'include' command:

<!--#set var="FORMAT" value="NONAMES" -->

(Note that the words 'FORMAT' and 'NONAMES' are all upper-case).

Showing the Date
By default the TFN Guestbook writes the date and time into a hidden HTML comment in your Guestbook when it adds an entry. To have the Date/Time appear as the first visible line of the Guestbook entry, just add the following line to the Thank-You page HTML code BEFORE the 'include' command:

<!--#set var="SHOWDATE" value="YES" -->

(Note that the words "SHOWDATE" and "YES" are upper case.)

No Censoring
By default the TFN Guestbook Utility censors out a few 'bad' words like the F-word, to help our members keep outsiders from messing up their pages. It's not perfect, so please be polite if you have to inform us of a missed word or clever trick used to bypass this simple filter. On the other hand, some people want NO censoring. They want every last word. This can be done by adding the following line to the Thank-You page HTML code BEFORE the 'include' command:

<!--#set var="CENSOR" value="NO" -->

(Note that the words "CENSOR" and "NO" are upper case.)

Getting Fancy - Changing Table/Field Attributes
Each entry in your Guestbook File consists of a small two-column table. The TFN Guestbook Utility tries to permit as much flexibility as possible in how a member chooses to format this table. There are three methods for affecting the appearance of the Guestbook. In order of increasing complexity, they are:

Setting the Table Border Color - Instead of the normal 'raised edges' you can set a solid color for your table border. This can look quite attractive when combined with style sheets (see below). Just add the following line to your Thank-You page HTML code BEFORE the 'include' command:

<!--#set var="BORDERCOLOR" value="color" -->

(The word "BORDERCOLOR" is all upper-case, and "color" is any color or color-code that you can normally use on a web page.)

Setting ALL Table Attributes - For full control over the appearance of each Guestbook entry, you can add the following line to your HTML code before the 'includel command:

<!--#set var="TABLE" value="attribute='value' attribute='value'..." -->

(The word "TABLE" is all upper-case, and "attribute='value'" are pairs of HTML attributes for the table. Note that value is enclosed by SINGLE-QUOTE marks because the entire string is enclosed by double-quotes. The default attributes used when 'TABLE' is not set are: "width='96%' border='0' cellpadding='1' cellspacing='0'". You will need to specify all of these if you want to add an additional element like background='imagename'.

Setting Table Attributes using STYLE SHEETS - One of the most flexible tools for formatting your webpage on newer browsers is the technique called 'Cascading Style Sheets'. This is a lengthy topic, with a great many options, beyond the scope of this document. The important point for users of the TFN Guestbook Utility is that all the table fields in the generated HTML tables have been assigned CLASSES and ID's, so that a single 'style' command in the Guestbook page header can change the appearance of the whole guestbook:
Enclose any of the following between <STYLE><!-- --></STYLE>:

table.fieldtable {attribute:value}
Certain attributes can be set for the whole table at once, like width and background. Notably, border color is NOT settable in this manner.
td.fieldname {attribute:value}
Many attributes, including text size and color, and background color can be set for the left column (field names)
td.fielddata {attribute:value}
Many attributes, including text size and color, and background color can be set for the right column (field data)
#fieldname {attribute:value}
Many attributes, including text size and color, and background color can be set for all the data fields with a specific name from your form. Note: Certain characters like spaces and underscores cannot be used in form field names when you want to use this feature.
#fieldnameNAME {attribute:value}
Many attributes, including text size and color, and background color can be set for the NAME (header) fields which have an ID consiting of the form field name followed by NAME (eg. 'From' has an ID of 'FromNAME').

Save a Plain Text Copy of the Form
In addition to (or instead of) the normal 'GUESTBOOK' update, you can have the Guestbook Utility insert the submitted form data into a plain text file. Just add the following line to your Thank-You page HTML code BEFORE the 'include' command:

<!--#set var="FILENAME" value="yourfilename" -->

(Note that the word "FILENAME" is upper case. "yourfilename" is the name of your text file in the same directory. This file must contain the 'INSERT' line described above.)

Send an E-Mail Copy of the Form
To have a copy of the submitted form e-mailed to the web page owner each time someone submits a guestbook entry just add the following line to the Thank-You page HTML code BEFORE the 'include' command:

<!--#set var="MAIL" value="YES" -->

(Note that the words "MAIL" and "YES" are upper case.)

If you want to offer your visitors the option of sending you a private e-mail via the form *instead* of adding it to your guestbook, include the following radio-check box field named PRIVATE (all caps) in your FORM (*not* in the Thank-You page):

<INPUT TYPE="checkbox" NAME="PRIVATE" VALUE="YES">

When your visitor clicks this checkbox, the form will be mailed and *not* added to the guestbook. Note that if you have set 'MAIL' to 'YES' in your Thank-You web page, you will always get an e-mail. In this case the PRIVATE field only determines whether to add the form to the guestbook.

E-Mail Recipient
When 'MAIL' or 'PRIVATE' is 'YES', the E-mail message generated is normally sent to the *owner* of the web page, which is the user-id that created the page. In some cases, where multiple user-id's have access to the same web space, the owner may not be the person who you want to receive the e-mail. In this case, you can tell the Guestbook Utility to send the e-mail to a different address. Just add the following line to the HTML code BEFORE the 'include' command:

<!--#set var="MAILTO" value="emailaddress" -->

Note that the word 'MAILTO' is all upper-case. Mail will always appear to come *from* the owner of the web page. If the E-Mail address is invalid, or cannot otherwise accept mail, the page owner will receive the mail instead. So it is strongly advised that pages with Mailto Forms are *not* owned by 'unused' accounts.

E-Mail Subject
Normally mail from your form arrives with the Subject Heading "Form Data". If you use mutliple forms with different purposes, you may specify different subject headings so that you can distinguish them in your incoming mailbox. To specify a custom Subject heading, add the following line to the HTML code BEFORE the 'include' command:

<!--#set var="SUBJECT" value="Your Subject Here" -->

(Note that the word 'SUBJECT' is all upper-case).

Custom Thank You Text
You can change the first line of text that the program generates (the 'Thank you for your submission') by adding the the following line to the HTML code BEFORE the 'include' command:

<!--#set var="THANKS" value="Your text Here" -->

(Note that the 'THANKS' is all upper-case).

Suppressing the Echoing of Submitted Information
If you wish to keep your Thank You Web Page short, you can optionally prevent the listing of submitted information from being echoed back to the person who just submitted it. Just add this set command to your HTML code BEFORE the 'include' command:

<!--#set var="FORMAT" value="NOECHO" -->

(Note that the words 'FORMAT' and 'NOECHO' are all upper-case). 'NOECHO' will not affect the format of your guestbook or e-mail. If you want to specify both 'NOECHO' and 'NONAMES' put them both in the same 'set' command, like this:

<!--#set var="FORMAT" value="NOECHO,NONAMES" -->

Changing Owner File Permissions to Execute
Sharp-eyed individuals will notice that the 'commands' for the TFN Guestbook Utility are all enclosed in HTML comments, much the same as Javascript. Unlike Javascript, these commands are not executed by the browser, but instead they are executed by the TFN Server before the page is sent to the browser. If you view the source for a "Thank You" page that has used the TFN Guestbook Utility, you won't see the commands listed above, you will see the "Thank You" text and HTML code generated by those commands.

In order to execute these kinds of commands (called Server-Side Includes), we need to set the file's 'owner execution' permission flag, so that the server will know to look for these commands hidden in the HTML comments. Note: TFN Information Providers (ip###) do NOT need to do this.

In Lynx (text/telnet sessions), changing file permissions is done on your "g files" display of your public_html directory. Highlight the name of the Thank You page to which you are adding the Guestbook command, press "m" (modify), then "p" (permissions). This will display a screen of checkboxes showing the current permissions for your web page. Move the cursor/highlight down to the 'Execute' box under 'Owner' and press right-arrow or Enter to put an "X" in the box ([X]). Then move the cursor down to the 'Submit Form' link at the bottom and press Enter to apply the changes to your page.

In Graphical browsers, you can click on the 'Telnet to TFN' link and follow the instructions above, or you can use the 'CHMOD' option in your FTP program. In WS-FTP_LE, you right click on the name of your web page in the 'Remote' (TFN side) directory display, and a menu will pop up with 'CHMOD (UNIX)' near the bottom. Click on that, and you will see a dialog box with permissions checkboxes. Check the box for 'Owner Execute' and click on 'OK' to apply the changes.

Guestbook Templates
There are three template files which you can copy to your personal web space. They don't use all the features of the guestbook, but are a quick and easy way to get one running. View each file in your browser, then View the Source and save or cut-n-paste to the file names indicated. Remember that all three files must be in the same directory and File permissions must be set on the thanks page.

This Guestbook Utility only works on TFN
Because it is executed by the server, the 'tfnguestbook' cgi program must be located on the same server where your web pages are located.

Back Front Contact

Copyright © 2002 Toronto Free-Net Inc.