Building A Quick-And-Dirty Guestbook With patGuestbook (part 2)

Learn to customize and secure patGuestbook.

Bells And Whistles

In the first part of this article, I gave you a quick rundown on the patGuestbook application, right from downloading the application to the nitty-gritty of installation, configuration and basic usage. This was followed by an express introduction to guestbook creation and deployment.

Now, in this concluding article, I shall focus on some of the bells and whistles offered by the application to the more enthusiastic developers out there (count me in as a permanent member of this group). Among the items under discussion: controlling the entries listed in the guestbook, customizing the user interface with the included patTemplate class, and protecting access to the application's administration module. Keep reading!

Adopting A Moderate Approach

If you recollect, one of the options available at guestbook creation time was related to guestbook entry moderation. In the first part of this article, I had decided to leave this at its default setting and not moderate the entries for my guestbook; as a result, entries were immediately displayed on the site as soon as they were entered.

However, in the real world, it is often essential to moderate the entries in the guestbook, and thereby control the content displayed to other visitors. And this is where patGuestbook's moderation feature comes in handy.

In order to enable moderation, you need to navigate back to the administration module, and select the "Voice of the People" entry from the drop-down menu at the top of the page. On the resulting information screen, navigate to the "General Settings" section, and check the box for guestbook moderation. Use the "Save Changes" button to record your changes, and the job is done!

Now, whenever a user tries to enter a comment in your guestbook, a message will appear indicating that the entry will be moderated,

The administrator - in other words, you - can then selectively approve or reject each comment via the site administration module. In order to do this, navigate back to the administration module, and select the "Voice of the People" entry from the drop-down menu at the top of the page. On the resulting information screen, navigate to the "General Settings" section and you will be presented with a list of all active and inactive entries.

You can update the status of each entry, and use the "Update Status" command to save your changes; all entries marked as active will not appear in the guestbook.

If Looks Could Kill...

Next up, interface customization. As you may already know, patGuestbook is tightly integrated with a sister project, patTemplate, a powerful PHP-based template engine (if you don't know how patTemplate works, you should read the introductory material at http://www.melonfire.com/community/columns/trog/article.php?id=130 and only then proceed forward with this tutorial). This template engine makes it fairly easy to create your own skins for the patGuestbook interface (and even share them with others, if you so desire).

First things first - where are the templates located? If you recollect, this location was specified as part of the configuration parameters located in the "patGuestbook.php" file in your installation's "config" directory:

Do those directory names ring a bell? They should - they're the template names that appear every time you create a new guestbook. So, if you want to create your own set of templates, this is obviously a good way to start.

Now, the patGuestbook application uses three different templates for rendering the user interface:

patGuestbookList.tmpl - this is the template that displays the entries in the guestbook

patGuestbookAdd.tmpl - this is the template which handles adding new entries to the guestbook

patGuestbookDisabled.tmpl - this template simply displays an error message when a particular guestbook is disabled

Let's start with the "patGuestbookList.tmpl" file. To make things easier, I'll give you a quick peek at the desired output before I explain the template's innards to you.

Now, if you take a close look at it, you'll see that this is very similar to the "textonly" template - all I've really done is add a navigation menu to the left side of the page.

I'm going to call my new template "melonfire" (feel free to name your appropriately), and so my first task is to create a directory parallel to the "pat' and "textonly" folders in the "skins" directory. Under this directory, I'll add an "img" directory to store images, and a "styles" directory to store stylesheets.

Next up, the page layout. After much thought and coffee-napkin scrawls, I decided on a simple two-column layout for my guestbook, with the navigation bar in the left column and the main guestbook content in the right one. Here's the basic skeleton:

Of course, since the menu is going to be constant across the pages, you can even abstract it into another template - I leave that to you as an exercise.

Bringing In The Database

At this point, I have identified the layout for the pages, and also shown you the menu that will be displayed on each page. Now for the most important item - connecting all this up to the patGuestbook database.

Once again, two special patGuestbook variables -{ENTRY_EMAIL} and {ENTRY_HOMEPAGE} - are used to retrieve the information entered by the user. I can also display the appropriate labels for each field via the {LABEL_EMAIL} and {LABEL_HOMEPAGE} variables.

How about displaying the heart of the guestbook - the user's comments?

The {URL_PREVIOUSPAGE} and {URL_NEXTPAGE} variables are used to display the links to the previous and next page, if required. the {URL_ADDENTRY} variable contains the URL that allows users to add a new entry to the guestbook.

A Well-Formed Plan

So that takes care of the main guestbook page - now how about customizing the input form for new entries?

The template that displays a message to the user when moderation follows the header.

<!-- message for moderated guestbook -->
<pattemplate:tmpl name="moderated" visibility="hidden">
Note that this guestbook is moderated, and your entry will only appear in the list of entries once it has been approved by a moderator.<br><br>
</pattemplate:tmpl>

This is followed by a list of error messages, which are displayed when required fields are left empty.

Feel free to edit the error messages above to reflect the personality and style of your site.

Finally, the meat of the template - the form that is displayed to the user. As usual, there are pre-defined patGuestbook templates that I can work with for this section. Remember to be careful when tweaking these templates (unless, of course, you're comfortable with patTemplate, in which case, tweak away!).

For each field in the guestbook, I have two tags - one displaying the label and the other displaying the form field to the user. For example, for the user's name, I've used the {LABEL_NAME} variable for the label and the {ENTRY_NAME} variable for the text box that is displayed to the user.

When Things Go Wrong

Finally, patGuestbook includes a template to display an error message to the user when a particular guestbook has been specifically disabled.

Pretty simple, this - plain ol' HTML, no fancy-shmancy gimmicks or convoluted variables. In order to see what it looks like, turn off a guestbook from the administration module and try accessing it - you should see something like this:

That's about it for the user interface templates that can be customized. If you thought that was easy and you're hankering for another challenge, you can always try customizing the administration module as well (alternatively, you could get up from your computer and go get yourself a life).

Locking It Down

If there is one drawback to the patGuestbook application, it is the lack of security for the administration module. By default, patGuestbook leaves the entire administration section totally unprotected and open to malicious attacks. If you're using the Apache Web server (you probably are), you can access the server's authentication features to add basic security to this section.

In order to illustrate how this works, let's consider a simple example. Let's assume the existence of the following directory structure:

This tells the server that access to the "admin" directory (the directory in which the ".htaccess" file is located) is to be controlled, and access is to be granted to users based on the username/password information in the file "/usr/local/apache/users"

The final step is to create the "users" file. Change to the "/usr/local/apache" directory (or whichever directory you've decided to store the user data in) and use the "htpasswd" command:

You can add more users to this file if you like (remember to omit the "-c" parameter for all subsequent additions, as that parameter creates a brand-new, empty file).

Remember not to store the "users" file in a directory under the server document root, or else malicious users will be able to view and download the password database through a browser.

Now, attempt to access the "admin" directory via your Web browser. The browser should pop up a dialog box and prompt you for a username and password. Access to the "admin" directory will be granted only if you enter a correct username and password, as defined in the "users" file.

Over And Out

And that's about all we have time for. In this two-part article, I introduced you to patGuestbook, a PHP application that makes setting up a guestbook on your site as easy as clicking your way through a series of menus. I showed you how to create a new guestbook, configure required and optional fields, and explore rating possibilities in your guestbook. I also showed you how to moderate entries as they are added, customize the user interface via the patTemplate engine, and protect unauthorized access to your guestbook with simple HTTP authentication.

In case you'd like to learn more about the topics discussed in this tutorial, take a look at the following links:

Note: All examples have been tested on Linux/i586 with Apache 1.3.28, PHP 4.2 and patGuestbook 1.0. Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!