uDirectory User's Manual

Business Edition

Version 1.3
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 uDirectory
  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 business 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 Business Edition of uDirectoryTM include: Looking for even MORE features? Be sure to check out the Deluxe Edition of uDirectoryTM at our website:

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


System Requirements

The Business 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 put 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 10 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_business.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";

7a. Who would you like to say the pages are created by?

At the bottom of each .html page that is generated by uDirectory, a message "This site was created by" is added. You can specify any name you want. For example, if you wanted to say that "This site was created by My Company", then you would specify this parameter as:

$created_by_name = "My Company";

7b. What is the company's website?

As described in question 7a, at the bottom of each .html page that is generated by uDirectory, a message "This site was created by " is added. You can have this link to any URL that you want. For example, if you wanted to say that "This site was created by My Company", and have the My Company part actually be a link to your website, then you would specify this parameter as the URL or your website:

$created_by_url = "http://www.mycompany.com";

8. 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";

9. Would you like to allow visitors to add and edit their own listings?

uDirectoryTM provides an option for you to allow visitors to add and edit their own listings. Set this parameter to "YES" if you want to allow visitors to add and edit their own listings. Otherwise, set this parameter to "NO".

Note: If you do set this parameter to "YES", then you will need to add a link on your web site to the following:

To add a new listing, link to:
http://www.mydomain.com/cgi-bin/udirectory_business.pl?command=add

To edit a listing, link to:
http://www.mydomain.com/cgi-bin/udirectory_business.pl?command=edit

Where the first part is actually the full path to this script on your server, and the last part is "?command=add" or "?command=edit".

$visitor_editing = "YES";


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_business.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_business.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 category or 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 "SEARCH" 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 uDirectory

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

Logging In

In order to start creating categories and listings, you must first login to uDirectory. 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_business.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 8 of the script setup.

Control Panel

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

Adding Categories

To add a new category, select the "ADD CATEGORY" button on the control panel. An "Add Category" form will then be displayed. Simply enter the name of the new Category and the name of the .html file for the category.

Deleting Categories

To delete a category, select the "DELETE CATEGORY" button on the control panel. A "Delete Category" form will then be displayed. Simply select the category that you want to delete. You will be prompted to confirm the deletion. Select "YES" to delete the file or "NO" to abort.

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 select the category into which the new listing will be added, then fill out the rest of the listing information. 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. Select the category in which the listing is in and enter the name of the business exactly as it appears in the listings (with case-sensitivity). 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. Select the category in which the listing is in and enter the name of the business exactly as it appears in the listings (with case-sensitivity). 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 automatically adds a category selection menu and a "GO" button onto every listing page that it generates. Visitors to your site can view the different directory categories by selecting the desired category and then pressing the "GO" button.

Searching The Listings

uDirectoryTM automatically adds a search entry box and a "SEARCH" button onto every listing page that is generates. Visitors to your site can search all of the listings by entering the business name (or just the start of the business name) and by then pressing the "SEARCH" button. A new .html page will be dynamically generated and which contains a list of all the businesses that fit the desired search criteria.

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

NEW! Visitors can now search the listings by business name or by description keyword by selecting search "By Business" or search "By Keyword", respectively. Note that searching by keyword will only look for one keyword at a time.


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 BUSINESS: start tag and ends with a END_FLAG end flag. DO NOT not remove these tags.
  2. Each listing has several tags such as business, contact, 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