uDirectory User's Manual

Personal Edition

Version 1.1
Copyright (c) 1998 - 2000; Microburst Technologies, Inc.
http://www.uburst.com

Table of Contents

  1. Introduction
  2. Features
  3. System Requirements
  4. CGI Script Configuration
  5. Installing The Script on Your Server
  6. Installation Debugging
  7. Using uDirectoryTM
  8. Viewing Listings
  9. Manually Editing The HTML Pages

Introduction

uDirectoryTM is an online directory and listing management system that allows you to easily create, update, and maintain an on-line directory..... without ever writing a single line of .html!

One single CGI script provides the ability to add, edit, and delete listings via an easy-to-use interface. The script automatically formats the listings and generates/updates the .html listing pages that visitors to the site will see. In addition, uDirectoryTM provides some nice features for your visitors such as a simple navigation system and a built in search feature.


Features

The features of the Personal Edition of uDirectoryTM include: Looking for even MORE features? Be sure to check out the Business and Deluxe Editions of uDirectoryTM at our website:
http://www.uburst.com/uDirectory/


System Requirements

The Personal Edition of uDirectoryTM consists of one Perl CGI script, so the only system requirement is:


CGI Script Configuration

uDirectoryTM has one CGI script that must be configured and installed on your server. To configure the script, you will need to open it with any standard text editor - such as NotePad or WordPad - and answer the 7 questions at the top of the script.

NOTE: If you've never installed or executed any Perl scripts on your server before, it is recommended that you first try installing our basic test script as described on the following reference page:

http://www.uburst.com/uStorekeeper/testscript.html

This is actually a reference page for one of our other products, but the concept is the same. By installing this basic Perl script, it should help you to understand how to install and execute scripts on your server. It also will verify that your web hosting account is configured properly to run Perl scripts and will make installing the uDirectoryTM scripts that much easier.

1. What is the location of perl on your server?

The uDirectoryTM script is written in the Perl programming language which is a standard on all servers. In order for this script to run, you must specify the location of Perl on your server. Typical locations are #!/usr/bin/perl, #!/usr/local/bin/perl, and #!/bin/perl. (Note that the #! characters are required and should be included when specifying the path). You can ask your Internet Service Provider for the location of Perl on your server.

Note: This path to Perl must be specified as the very first line of this script.

2. What directory would you like to put the directory's .html files?

This is the directory on your server where you would like to put all of the .html files that uDirectoryTM creates.

You will need to create this directory on your server yourself and give it read, write and execute permissions (chmod 777).

You will need to specify the path to this directory via the $relative_directory parameter. When specifying the path, it must be specified as either 1) The full path from the root directory on your server (something like "/www/htdocs/listings/") or 2) The relative path from your CGI directory (something like "../listings/").

For example, suppose you wanted all of the .html files to be put in a directory called "listings" which is a subdirectory in you main document directory. You would have to make a subdirectory within your main document directory called "listings", give it read, write, and execute permissions (chmod 777), and then specify the $relative_directory parameter as:

$relative_directory = "../listings/";

Note: To edit this, you can literally replace or type over this line in the CGI script.

3. What is the full URL of the directory you specified in step 2?

This URL will be inserted into the .html pages that are created by uDirectoryTM. uDirectoryTM uses it to create links to the other uDirectoryTM generated .html pages. It should be specified as the full URL of the directory you specified in step 2. For example:

$directory_url = "http://www.mydomain.com/listings/";

4. What is the full url of this script on your server?

This URL will also be inserted into the .html pages that are created by uDirectoryTM. It should be specified as the full URL of where this script will be installed on your server. For example:

$script_url = "http://www.mydomain.com/cgi-bin/udirectory_personal.pl";

5. What image would you like to put on each page?

This is another URL that will be inserted into the .html pages that are created by uDirectoryTM. It allows you to specify the full URL of an image or logo that you would like to appear on each of the directory pages. For example, if you had an image in your images directory called "myimage.jpg" and you wanted this image to appear on evey directory listing page, then you would specify this parameter as:

$image_url = "http://www.mydomain.com/images/myimage.jpg";

6. What background image would you like on the pages?

uDirectoryTM allows you to specify the URL of a background image that will be put on each .html page that uDirectoryTM creates. This will be something like:

$background_image = "http://www.mydomain.com/images/mybackground.jpg";

If you do not want a background image, then set this parameter to "NONE":

$background_image = "NONE";

7. What password would you like to use to login?

This is the password that must be entered each time you wish to use uDirectoryTM to add/edit/delete a directory listing. It is to prevent other people from being able to change the listings. You can specify any password. For example, if you wanted your password to be "hello", then specify this parameter as:

$login_password = "hello";


Installing The Script on Your Server

After editing the script, as described in the previous section, you will need to transfer the file to the CGI directory on your server. Transfer it as a normal ASCII or TEXT file - as opposed to a BINARY file. Put it in the cgi directory on your server and change the permissions on the file to read and execute (chmod 755). (If you have an NT server, you may have to get your web hosting provider to give the script execute permissions for you.)

TIP: You can test that the CGI script is setup correctly by opening up your browser and typing the full path of the script on your server into the LOCATION box on your browser. This URL should be the same URL that you specified in question #4 of the script setup, such as:

http://www.mydomain.com/cgi-bin/udirectory_personal.pl

Upon doing so, you should see the "Login" screen similar to when you go to the URL of the script on our site:

http://www.uburst.com/cgi-bin/udirectory/udirectory_personal.pl

If you do not see the login page and instead see a "Server Error", then something is not setup correctly, see the Debugging section below.


Installation Debugging

Problem: I get a "Server Error" when I try run the script.
Solution: A "Server Error" could be caused by one of three things:
  1. The path to Perl is incorrect. Double-check your path to Perl. It should be something like this: #!/usr/bin/perl or on NT Servers, something like this: #!C:/perl/perl.exe If you are not sure of the location of Perl on your server, ask your web hosting provider.
  2. The script doesn't have execute permissions. Make sure that you gave the script execute permissions. On UNIX servers, use your FTP program to do a chmod 755 on the script. On NT servers, you may have to ask your web hosting provider to give the script EXECUTE permissions.
  3. The script was transferred in BINARY or RAW transfer mode. When transferring Perl scripts to your server, be sure to transfer the script in ASCII or TEXT transfer mode. Do NOT transfer the script in BINARY or RAW transfer mode (doing so will usually result in an "Incomplete set of headers" Server Error).
Problem: The script is being displayed instead of being executed.
Solution: If when you go to the URL of the script on your server, the script is being displayed rather than executed, the problem will be one of two things:
  1. The script doesn't have execute permissions. Make sure that you gave the script execute permissions. On UNIX servers, use your FTP program to do a chmod 755 on the script. On NT servers, you may have to ask your web hosting provider to give the script EXECUTE permissions.
  2. The extension on your script is incorrect for your server. That is, some servers require that Perl scripts end with the extension ".pl" while other servers require that Perl scripts end with the extension ".cgi". If you do not know the correct extension to use on your server, as you web hosting provider what the file extention of Perl CGI scripts should be.
Problem: The script is trying to be downloaded instead of being executed.
Solution: If when you go to the URL of the script on your server, the script is trying to be downloaded rather than executed, the problem will be one of two things:
  1. The script doesn't have execute permissions. Make sure that you gave the script execute permissions. On UNIX servers, use your FTP program to do a chmod 755 on the script. On NT servers, you may have to ask your web hosting provider to give the script EXECUTE permissions.
  2. The extension on your script is incorrect for your server. That is, some servers require that Perl scripts end with the extension ".pl" while other servers require that Perl scripts end with the extension ".cgi". If you do not know the correct extension to use on your server, as you web hosting provider what the file extention of Perl CGI scripts should be.
Problem: If I type the script path directly into the LOCATION box on my browser, I correctly get the LOGIN page, but once I try to login I get a server error or file not found error.
Solution: This will usually be caused by having the wrong path to the CGI script specified in question 4 of the script setup. Double check your setting for question 4.

Problem: I get an "Unable To Open" error.
Solution: Unable to open errors are usually cause by one of three things:
  1. The relative directory that you specified in question 2 of the script setup is incorrect. Double-check that your relative path from your CGI directory to your "listings" directory is correct. If in doubt, perhaps try specifying question #2 in the script setup to be the FULL PATH to your listings directory. (Do NOT use a URL beginning with "http" as the setting for question #2. The $relative_directory setting must be a directory path - NOT a URL).
  2. The "listings" directory that you specified in question 2 of the script setup does not exist. Make sure that you actually created the "listings" directory that you specified in question #2 of the script setup.
  3. Your "listings" directory does not have WRITE permission. Make sure that you have given your "listings" directory WRITE permission. For UNIX servers, use your FTP program to do a chmod 777 on that directory. For NT servers, you may have to get your web hosting provider to give your "listings" directory READ and WRITE permissions (permission to allow CGI scripts to WRITE to that directory).
Problem: Whenever I try to create a listing, I get an "Unable to open....." error.
Solution: This is usually caused by one of three things:
  1. The relative directory that you specified in question 2 of the script setup is incorrect. Double-check that your relative path from your CGI directory to your "listings" directory is correct. If in doubt, perhaps try specifying question #2 in the script setup to be the FULL PATH to your listings directory. (Do NOT use a URL beginning with "http" as the setting for question #2. The $relative_directory setting must be a directory path - NOT a URL).
  2. The "listings" directory that you specified in question 2 of the script setup does not exist. Make sure that you actually created the "listings" directory that you specified in question #2 of the script setup.
  3. Your "listings" directory does not have WRITE permission. Make sure that you have given your "listings" directory WRITE permission. For UNIX servers, use your FTP program to do a chmod 777 on that directory. For NT servers, you may have to get your web hosting provider to give your "listings" directory READ and WRITE permissions (permission to allow CGI scripts to WRITE to that directory).
Problem: Whenever I try to use the "Goto Listings" button on the control panel, I get a file not found error.
Solution: This is usually caused by having the wrong directory URL specified in question 3 of the script setup. The $directory_url parameter should be specified as the full URL to the directory on your server where the .html listing pages are located (as specified in question 2 of the script setup).

Problem: Whenever I try to use the "FIND" or "GOTO" feature on the listing pages, I get an error.
Solution: This is usually caused by having the wrong path specified in question 4 of the script setup. The $script_url should be set to the full URL of the CGI script on your server (The same URL that you type in to login to uDirectoryTM).

Problem: After adding new listings with uDirectoryTM, when I go to the directory listings I don't see the new listings.
Solution: Press RELOAD on your browser in order to make your browser read the latest pages.

Still having a problem? Be sure to check out our uDirectoryTM Reference Site for the latest in troubleshooting information:

http://www.uburst.com/uDirectory/reference.html


Using uDirectoryTM

Once the CGI script is correctly installed on your server, you are ready to start using uDirectoryTM.

Logging In

In order to start creating/editing listings, you must first login to uDirectoryTM. To get to the login screen, just use your browser and go to URL of the uDirectoryTM script on your server. This will actually be the same URL that you specified in question 4 of the script setup. It will be something like:

http://www.mydomain.com/cgi-bin/udirectory_personal.pl

TIP: To make logging in easier, you may want to bookmark this page.

To login, just enter the password that you specified in question 7 of the script setup.

Control Panel

Once you successfully login to uDirectoryTM, you will see a page with a control panel on it. From this control panel page you can add, edit, and delete listings or go to the actual listing pages.

Adding Listings

To add a new listing, select the "ADD LISTING" button on the control panel. An "Add Listing" form will then be displayed. Simply enter the name (last name first) and other listing information and then press "SUBMIT". Note that if you are going to include an image for the listing, the ideal size for the image is 100x100 pixels.

Editing Listings

To edit a listing, select the "EDIT LISTING" button on the control panel. An "Edit Listing Selection" form will then be displayed. Enter the last and first name of the listing you want to edit exactly as it appears in the listings. Upon submitting, an "Edit Listing" form with the selected listing will be displayed. Simply change the fields that you want change.

Delete Listings

To delete a listing, select the "DELETE LISTING" button on the control panel. A "Delete Listing Selection" form will then be displayed. Enter the last and first name of hte listing you want to delete exactly as it appears in the listings. Upon submitting, you will be prompted to confirm the deletion. Press "YES" to delete the listing or "NO" to abort.

Goto Listings

To go to the actual listing pages from the control panel, simply press the "GOTO LISTINGS" button. Note: If you use the "GOTO LISTINGS" button you may not see any new changes to the listings since the last time you viewed the listing pages. To see the latest listings, you may need to reload the pages with your browser by pressing you browser's "RELOAD" button.


Viewing Listings

All .html pages that are generated by uDirectoryTM will be located in the directory that you specified in questions 2 and 3 of the script setup. Therefore, you should add links on your home page to link visitors to this directory.

Viewing Different Categories

uDirectoryTM will automatically separate the listings into 26 categories - one for each letter of the alphabet. Listings with last names beginning with "A" will be put in the "A" category, listings with last names beginning with "B" will be put in the "B" category, and so on.... uDirectoryTM will automatically put a link to each of the categories at the top of every listing page that it generates. Visitors to your site can view the different directory catagories by selecting the desired letter link at the top of the listing page.

Searching The Listings

uDirectoryTM automatically adds a search entry box and a "FIND" button onto every listing page that it generates. Visitors to your site can search all of the listings by entering the first and/or last name that they want to search for. The results of the "FIND" feature will automatically link the visitor to the first listing with the specified name on the corresponding category page.

Note: You do not need to use any wild cards such as an asterisk (*) when searching for a last name. For example: If you want to search for all listings that start with a "MC", then you would type MC in the search entry box and press the "FIND" button.


Manually Editing The HTML Pages

Although you should not need to, you can manually edit the .html listing pages that uDirectoryTM generates, provided you follow a few guidelines:
  1. Each listing begins with a NAME: start tag and ends with a END_FLAG end flag. DO NOT not remove these tags.
  2. Each listing has several tags such as last_name, first_name, etc. These tags must be at the beginning of the lines in order for the edit features to work properly. DO NOT remove these tags.
  3. So in general, just keep the format of the listings the same as they are when uDirectoryTM creates them.

For additional information about uDirectoryTM or to find out about other great products from Microburst Technologies, Inc., please visit our website at:
http://www.uburst.com