State of Oregon - Online Services 155 Cottage St NE Salem OR 97301 Phone: 503-378-2135    Fax: 503-378-5543 Email: support@dialoregon.net

Online Services shall in no way be responsible for any damages or losses resulting from the use of any of these services. Please refer to the Online Services User Agreement for further details on usage policy.

This document explains how to set up your own personal guest book. Please be sure to read the requirements section. The options section provides information on using and configuring your guest book.

Overview

The guest book file is the HTML page used to store your guest book signatures. Each time someone signs your guest book, the guest book script appends the input to your guest book file. In order for the guest book script to append input to your guest book file, you must first create your guest book file using this form (see requirement 3 below). To view the signatures in your guest book, simply create a link to your guest book file. You may further customize the format of your guest book file with a template (see option 6 below).

The guest book form is the HTML form interface to your guest book file. It provides the text fields that people will use to enter their name, e-mail address, home page and comments when they sign your guest book. There is no standard for this page. You may use any valid HTML tags, but you must abide by the requirements and options listed below.

Requirements

2. The opening <form> tag in your guest book form must be:

<form method="POST" action="/cgi-bin/guestbook.cgi">

3. A guest book file must be created in your public_html directory. The guest book file is the HTML page that the guest book script will write to each time someone "signs" your guest book. You must use this form to create your guest book file. You will use the name of this file to set the gbfile variable (see option 1 below) in your guest book form.

4. Once you have created your guest book file you will need to create the HTML form interface to your guest book. The easiest way to create this form is to copy this sample guest book form and modify it for your own needs. At the least, you will need to set the gbfile variable in the form (see option 1 below) to your own guest book file. The guest book form can be located anywhere under your public_html directory on the web server.

Options

1. You must set the gbfile variable using a hidden field in your form. The value of this field should be the name of your guest book file. The guest book file must reside in your public_html directory. For example, if your guest book file is guest.html, then you would add

<input type="hidden" name="gbfile" value="guest.html">

2. You can require users to fill in any of the four guest book fields using the _req extension in a hidden input field. For example, if you want to require users to fill in the name field, you would add

<input type="hidden" name="name_req">

3. The guest book can perform some simple e-mail and URL validation on user input. E-mail validation will check to see that any input for the e-mail address is of the general form username@domain.name. It will not verify that the e-mail address actually exists. URL validation will check to see that any input for the URL begins with http://. It will not verify that the URL actually exists.

You can turn on validation for either field with the _val extension. For example, to have the guest book perform e-mail validation, add

<input type="hidden" name="email_val" value="on">

4. A common problem with displaying user input on an HTML page is the use of embedded HTML tags. Allowing users to include HTML tags in their input can cause problems if the tags are inappropriately used. By default, the guest book will remove all HTML tags. If you want to allow HTML tags in a field, you can turn this option on with the _tags extension. For example, if you want to allow HTML tags in the comments field, then you would add

<input type="hidden" value="comments_tags" value="on">

5. You can redirect the user to a specified URL after they sign your guest book using the url_sys variable.

<input type="hidden" name="url_sys" value="http://www.dialoregon.net">

6. You may use a template to customize the look of your guest book. Each time someone "signs" your guest book, the form input is appended to the end of your guest book file. A template allows you to customize how that input is written. It contains the HTML code that the guest book will use each time it writes to your guest book file. Embedded in the code are variables that will be substituted with the corresponding form input. If you do not use a template, a default guest book format will be used instead.

You create a template file using the name of your guest book file and the .gb extension. For example, if your guest book file is guest.html, then your template file will be guest.gb. The template file must reside in your public_html directory. You may use any valid HTML tags in your template, but keep in mind that this will be appended to the end of the same file each time.

To place the user form input into your template, you will use the corresponding variable names below:
$name - will be replaced with user's name
$email - will be replaced with user's email address
$url - will be replaced with user's URL
$comments - will be replaced with user's comments

In addition to the above variables, you can also include the following:
$date - will be replaced with the date and time
$ip - will be replaced with user's IP address
$browser - will be replaced with user's browser type

This is an example of the default guest book format. Although you may change the background and header, the format of the user input will always be the same.

This an example of a guest book using a template file and the source for the template file. Each variable in the template is replaced with the corresponding user input when someone signs this guest book. You may use a variable more than once in the same template or not at all. The email and url variables will not be hyperlinks by default. You are responsible for making them links in your template.

7. You may have an e-mail notification sent to you when someone signs your guest book. Use the mailto_sys hidden variable to specify the e-mail address.

<input type="hidden" name="mailto_sys" value="user@foo.com">

8. You may edit your guest book file using any text editor. Do not delete the guest book file from your public_html directory during the edit process. If you do delete your guest book file, you will need to create a new one using this form.