uDirectory User's Manual

Deluxe Edition

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

Table of Contents

  1. Introduction
  2. Features
  3. System Requirements
  4. Getting Started
  5. Configuring The Script
  6. Transferring The Script To Your Server
  7. Using uDirectory
  8. Listing Configuration Form
  9. Utilities
  10. Viewing Listings
  11. FAQ
  12. Troubleshooting
  13. Data Format and Importing Data

1. Introduction

uDirectoryTM is an online directory and listing management system that allows you to easily create, update, and maintain on-line listings..... 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.


2. Features

The features of the Deluxe Edition of uDirectoryTM include:

3. System Requirements

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


4. Getting Started

Upon receiving uDirectory, you should:
  1. Unzip the entire uDirectoryTM .zip file into a directory on your local desktop computer.

  2. Follow the directions in the section Configuring The Script in order to configure the script for your server.

  3. Follow the directions in the section Transferring The Script To Your Server in order to transfer the script to your server.

  4. Start Using uDirectory!

5. Configuring The Script

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 17 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 script 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 most servers. In order to run this Perl script, you must specify the location of perl on your server.

    NOTE 1: The path to perl should be specified as the very first line at the top of the script and should include the #! characters in front of the path.

    NOTE 2: On UNIX servers, typical values are:
    #!/usr/bin/perl
    #!/usr/local/bin/perl
    #!/bin/perl

    NOTE 2: On NT servers, typical values are:
    #!c:/perl/perl.exe
    #!c:/perl/bin/perl.exe

    NOTE 4: Some NT servers do not require that this path be specified at all. If that is the case for your server, just leave the first line of this script as is.

    (If you do not know the path to Perl on your server, ask your web hosting provider.)


  2. What is the full url of this script?

    The $script_url parameter below must be set to the full URL of the script on your server. For example, if you put the script into your cgi-bin directory, then you should set this value to something like:

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

    Note: Some servers require that CGI scripts end with .pl and other servers require that scripts end with .cgi. Remember that if you have to rename the script to use the .cgi file extension instead of the default .pl file extension, then be sure to use udirectory.cgi instead of udirectory.pl in this parameter.


  3. What is the full url of the directory that you would like to put the HTML pages that are generated by uDirectoryTM?

    This is the directory on your website that you would like to contain all of the HTML pages created by uDirectoryTM. For example, if you wanted to put the HTML files in a directory on your site called "listings", then you should set this value to something like:

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

    Note 1: You will have to create this directory yourself and give it read, write and execute permissions.

    Note 2: For UNIX servers, you should be able to use your FTP program to change the permissions to read, write and execute (chmod 777).

    Note 3: For NT servers, you may have to get your web hosting provider to give this directory read, write and execute permissions.


  4. What is the local path on your server to the HTML directory that you specified in question #3?

    In order to be able to write the HTML files to the directory you specified in question #3, you must specify the path to that directory on your server. This path can be specified as a relative path - relative to the location of the script in your CGI directory - or as the full path to the directory from your root directory.

    Note 1: An example of a relative path (from your cgi-bin to your listing directory) would be:

    $html_directory = "../listings/";

    Note 2: An example of a full path (directly to your listing directory) would be:

    $html_directory = "/www/htdocs/listings/";

    (If you want to use the full path to your directory, you may need to ask your web hosting provider what the full path to your directory is. Note that this is NOT your URL and should NOT begin with http://....)


  5. What image would you like to appear on the Control Panel page?

    In order to create, edit, and maintain the listings with uDirectoryTM, the administrator of the site will be using uDirectory's Control Panel. With the $image_url parameter, you can specify an image that will appear on the Control Panel page. It can be any image/logo you like. An example setting for this parameter would be something like:

    $image_url = "http://www.mydomain.com/images/mylogo.gif";

    Note 1: This parameter must be specified as the full URL of the image.

    Note 2: It is recommended to keep the size of this image to be around 200 x 200 pixels.

    Note 3: This is also the image that will appear on the Search Results pages, so keep that in mind.


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

    In order to protect the listings and only allow the administrator to have full control over the listings, a password must be used. An example setting for this parameter is:

    $master_password = "mypassword";


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

    At the bottom of each HTML page that is generated by uDirectoryTM, a message "This site was created by" is added. You can specify any name and URL you want here. For example, if you wanted it to say that "This site was created by My Company" and you wanted this to be a hyper-link to your company's URL, then you would specify the parameters as:

    $created_by_name = "My Company";
    $created_by_url = "http://www.mydomain.com";

    Note: If you do not want this "created by" message put at the bottom of each page, then set these values to "NONE".


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

    With this parameter, you can specify whether visitors to the website will be allowed to add and edit their own listings. If you want to allow visitors to add and edit their own listings, set this parameter to:

    $visitor_editing = "YES";

    Otherwise, set this parameter to:

    $visitor_editing = "NO";

    Note: See the section on Allowing Visitors to Add/Edit Listings for more information about how to add links to your web pages.


  9. Would you like to be notified via email each time a listing is added?

    uDirectoryTM now has the option to notify the administrator (via email) each time a listing is added/edited. This can be useful if you want to be able to review the content of the listings - or just know whenever a new listing has been added. If you would like to notify the administrator of changes, set the notify parameter to:

    $notify = "YES";

    Otherwise, set the parameter to:

    $notify = "NO";

    Note: An email will only be sent when visitors add/edit listings. No email will be sent if you add/edit listings while logged in as the administrator.


  10. What is the email address of the administrator?

    This should be the email address of the person who will mainly be in charge of maintaining the site (the uDirectoryTM administrator). If using the "notify" option described in question #9, then this will also be the email address that change notifications will be sent to. An example value for this parameter would be something like:

    $gEmail_address = 'webmaster@mydomain.com';


  11. What subject would you like to appear emails that are sent to the administrator?

    If using the notify option to notify the administrator whenever a listing is added/edited, you can use this parameter to specify the subject that will appear on the email notifications. An example value for this parameter is:

    $gEmail_subject = "uDirectory Notification";


  12. Would you like to use 'sendmail', 'sockets' or 'blat' to send email?

    In order to take advantage of the email notifications or other email utilities, you must configure the email method you would like to use. With the $gEmail_method parameter you can specify "SENDMAIL", "SOCKETS", or "BLAT".

    Note 1: For UNIX servers, it is recommended to use sendmail. (Sendmail is an email utility that is standard on most UNIX servers). To use sendmail, set this parameter to:

    $gEmail_method = "SENDMAIL";

    Note 2: For NT servers, you must use SOCKETS or BLAT:

    $gEmail_method = "SOCKETS";

    or

    $gEmail_method = "BLAT";


  13. What is the location of sendmail on your server?

    In order use sendmail to send email, you must specify the location of sendmail on your UNIX server. Typical locations of sendmail are /usr/lib/sendmail, /usr/bin/sendmail, or /usr/sbin/sendmail. If you do not know the location of sendmail on your server, you can ask your web hosting provider for the path to sendmail.

    Note 1: An example setting for this parameter is:

    $sendmail_path = "/usr/lib/sendmail";

    Note 2: If you specified question #12 as "SOCKETS" or "BLAT", then you can skip this question.


  14. What is the address of your mail server?

    In order to send email via SOCKETS, you must specify your mail server either by name (such as postoffice.mydomain.com) or by IP address (such as 123.456.789.0). If you do not know the name or IP address of your mail server, you should be able to ask your web hosting provider.

    Note 1: An example setting for this parameter is:

    $smtp_address = "123.456.789.0";

    Note 2: If you specified question #12 as "SENDMAIL" or "BLAT", then you can skip this question.


  15. What is the location of blat on your server?

    In order use 'blat' to send email, you must specify the location of sendmail on your NT server. Typical locations of 'blat' are C:/Blat/blat.exe or C:/Progs/Blat/blat.exe. If you do not know the location of 'blat' on your server, you can ask your web hosting provider for the path to blat.

    Note 1: An example setting for this parameter is:

    $blat_path = "C:/Blat/blat.exe";

    Note 2: If you specified question #12 as "SENDMAIL" or "SOCKETS", then you can skip this question.


  16. What is the maximum number of listings to be displayed per page?

    In order to prevent any one category page from becoming too large (and taking a long time to view), this $max_listings_per_page parameter has been added. The $max_listings_per_page parameter allows you to specify the maximum number of listings that will appear on any one category page. If the number of listings in a category exceeds the value of this parameter, additional HTML pages for the affected category will automatically be created with "NEXT" links added as needed. Depending on the number of fields that you have in your listings, a typical value for this parameter might be:

    $max_listings_per_page = 10;

    Note: Do NOT use quotes when specifing this parameter.


  17. OPTIONAL SETTINGS

    Listed under configuration question #17 are several preference settings such as fonts and colors. Most people will accept the defaults as listed, but you may change some of the self-explainatory settings if desired.

    Note 1: If you change these after you have already started creating categories, don't forget to use the "Generate HTML" Utility to re-generate all of the HTML pages and have these settings take effect.

    Note 2: Some of the default category settings will be over-written by your individual category settings.

After editing the script and configuring the 17 questions described above, you are ready to Transfer The Script To Your Server. (proceed to the next section)


6. Transferring The Script To Your Server

After editing the script and configuring the settings as described in the previous section, you will need to use your FTP program to transfer the file to the CGI directory on your server and give the script READ and EXECUTE permissions. While doing so, be aware of the following notes:

Note 1: Be sure to transfer the script as a normal ASCII or TEXT file - as opposed to a BINARY file.

Note 2: Be sure to transfer the script to the CGI directory on your server. On most servers, this directory will be called cgi-bin or cgi-local.

Note 3: Be sure to give the script read and execute permissions (chmod 755). If your server is a UNIX server, you can use your FTP program to give the file READ and EXECUTE permissions. If your server is an NT server, then you may have to get your web hosting provider to give the script READ and EXECUTE permissions.

Note 4: If you haven't already, be sure to also make the listings directory on your server too. (as described in question #3 of the Configuring The Script section).

TIP: You can test that the CGI script is setup correctly by opening up your browser and typing the full URL of the script on your server into the LOCATION box on your browser. For example:

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

If it returns a "LOGIN" page, then the script is configured correctly. If not, then something is not setup correctly, see the Troubleshooting section below.


7. Using uDirectory

Once the CGI script is correctly configured and 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 #2 of the Configuring The Script section. It will be something like:

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

To login, just enter the password that you specified in question #6 of the Configuring The Script section.

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

Control Panel

Once you successfully login to uDirectory, you will see a page with a control panel on it. This is the main control panel from which the administrator can configure, add, edit and maintain the listings. The function of each button in this control panel is described below.

Listing Configuration

The Configure Listings button will create a form from which the administrator can configure the names and types of the fields that will be maintained in the listings. Configuring the listings should actually be the first thing you do when setting up your listings, however, you will be able to go back and modify these settings whenever you like. For a complete description of the Listing Configuration form, see the Listing Configuration Form section below.

Utilities

The Utilities button will create a form from which the administrator will have access to the print, mailer, and other utilities offered by uDirectoryTM. For a complete description of the Utilities form, see the Utilities section below.

Adding Categories

The Add Category button will create a form from which the administrator can add a new category. Options on the form allow you to configure the name of the new category, an image that will be placed on the category page, a background image for the category page, and background and text colors. For advanced users, there are three sections on the form where extra .html will be added to the top, middle, or bottom of the category page.

Note: The only required field is the Category Name. This name must be unique.

Editing Categories

The Edit Category button will allow the administrator to select one of the pre-existing categories and then create a form from which the administrator can edit the current settings of the category.

Deleting Categories

The Delete Category button will allow the administrator to delete a category. The administrator will be prompted to select the category to delete and then will be prompted to confirm the deletion. Select "YES" to delete the file or "NO" to abort.

Copying Categories

The Copy Category button will allow the administrator to copy the entire contents of one category to a new category. The administrator will be prompted to select the category to copy and then will be prompted to enter the name of the new category.

Adding Listings

The Add Listing button will create a form from which the administrator can add a new listing. The fields on the Add Listing form will correspond to the settings configured on the Listing Configuration form. A preview page will be displayed after entering the listing information to allow the administrator to preview what the listing will look like. Press the "ACCEPT" button to confirm the new listing and add it to the listing pages.

Note: Since this Add Listing button is only accessible to the administrator, even if uDirectoryTM is configured to send email notifications when listings are added/edited, no email will be sent. Email notifications will only be sent when visitors add/edit listings.

Editing Listings

The Edit Listing button will allow the administrator to select one of the pre-existing listings and then generate an Edit Listing form from with the listing can be modified. The fields on the Edit Listing form will correspond to the settings configured on the Listing Configuration form and will contain the current values of the listing being edited. A preview page will be displayed after modifying the listing information to allow the administrator to preview the changes to the listing. Press the "ACCEPT" button to confirm the changes to the listing and to update the listing pages.

Note: Since this Edit Listing button is only accessible to the administrator, even if uDirectoryTM is configured to send email notifications when listings are added/edited, no email will be sent. Email notifications will only be sent when visitors add/edit listings.

Deleting Listings

The Delete Listing button will allow the administrator to delete a listing. The administrator will be prompted to select the category of the listing and the name of the listing that is to be deleted and then prompted to confirm the deletion. Select "YES" to delete the file or "NO" to abort.

Copying Listings

The Copy Listing button will allow the administrator to copy a listing from one category to another. The administrator will be prompted to select the category of the listing to be copy, the name of the listing to be copy, and then the new category to which the category will be copied to.

Goto Listings

The Goto Listings button will link the administrator to the actual listing pages.

Note: When viewing the listings, you may not see any of the 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 your browser's "RELOAD" button.

Move Listing

The Move Listing button allows the administrator to move a listing from one category to another. The administrator will be prompted to select the category of the listing to be moved, the name of the listing to be moved, and then the new category to which the category will be moved to.


8. Listing Configuration Form

The Listing Configuration Form allows the administrator to configure the names and types of the fields that will be maintained in the listings. This section describes how to configure the different sections of the Listing Configuration Form.

Main Field Configuration

In the Main Field Configuration textbox, enter the name of the key field that your directory will maintain. That is, whatever name you enter for this field will appear as the first field on the add listing form. This will also be the first field that is displayed on your listing pages.

For example, if you wanted your directory to be a directory of Business Listings, then you might enter Business Name for this field.

Or as another example, if you wanted your directory to be a directory of Classified Ads, then you might enter Title of Ad for this field.

Password Field Configuration

In the Password Field Configuration section, you can select whether you would like each user to be able to password-protect his/her listing. Note that if you chose to use this option, the uDirectoryTM administrator will still be able to edit/delete the listings. Select "YES" if you would like users to be able to password-protect their listings. Otherwise, select "NO" if you do not want user's to be able to password-protect their listings.

Image Field Configuration

In the Image Field Configuration section, you can specify whether you would like allow a user-specified image/logo that will be displayed next to each listing. If you do want to allow images, then you will need to select whether you want the "Image on Left", "Image on Right", or "Image on Top". If you do not to allow images, select "No Image".

Note 1: If you do want to allow images, you will also need to specify the width and height of the images. You can specify any size, but remember that the larger the images, the longer the pages will take to load.

Note 2: If you want the image to be a hyperlink to another URL, then be sure to select the appropriate field number in the Associate Image Link with menu. The field number that you choose here should correspond to a URL-Type field configured in the General Field Configuration section below.

Note 3: Even if you do allow users to specify an image that is to be associated with their listing, they will not be required to do so (uDirectoryTM will just generate the listing .html without an image if they do not enter one).

Description Field Configuration

In the Description Field Configuration section, you can specify whether you would like a large description area associated with each listing. That is, if you decide to use this field, it will appear as a large area on the ADD LISTING form where the user can enter multiple lines of information - such as a description, advertisement, etc.... This field will appear as slightly larger text in the listing - directly after the key field configured above in the Main Field Configuration section.

Note 1: If you want to use this field, specify the name of the field in the text box (such as "Description" or "Advertisement") and select either STANDARD or REQUIRED for the type.

Note 2: If you do not want to use this field, select "NOT USED" for the type.

Note 3: The only difference between this field and any fields configured in the General Field Configuration section below as of type "TEXT AREA", is that this description field will have larger text and will appear immediately below the Main Field.

General Field Configuration

In the General Field Configuration section, you can configure up to 20 additional fields that are to be maintain in the listings. For each field, you can specify the name of the field, the type of the field, and how the field is to be displayed.

Note 1: Specify the name of each field that you are going to use in the first editbox next to the field.

Note 2: For the TYPE, select:
Note 3: For the DISPLAY, select:

9. Utilities

The Utilities form allows the administrator to access any of the utilities that have been built into uDirectory. This section describes each of the uDirectoryTM utilities.

Generate HTML

The Generate HTML button allows the administrator to force uDirectoryTM to regenerate all of the listing .html pages from the uDirectoryTM data files. This comes in handy if any of the uDirectoryTM data files are manually edited and thus, need the .html pages to be updated to reflect the data files. See the section on Data Format and Importing Data for more information about manually editing the uDirectory data files.

Print

The Print button allows the administrator to view the data for a specified category in a format that is ideal for printing. That is, the Print utility will display the listing information for a specified category in a smaller font and without images - so that the data can be easily printed by selecting "Print" from the browser's menu.

Mail

The Mail utility allows the administrator to send an email to all email addresses contained in the listings of a specified category. That is, the administrator will be able to specify the email's subject and message and then select the category to which to send the email. The email utility will then send the email to the first field of type "EMAIL ADDRESS" in each listing of that category.

Note 1: A preview email page will be displayed before the email is actually sent so that you can double-check the message and address list before confirming and sending the email.

Note 2: If the listings are configured with more than one field of type "EMAIL ADDRESS", only the first email address field of each listing will be sent the email.

Note 3: Depending on how many listings are in the category and how fast the mail server is, it may take a while to send the email to all of the addresses. For this reason, uDirectoryTM will not wait for the email to finish being sent, but rather, will just email the administrator with a receipt email once the email is finished being sent to all of the addresses. In general, the email process should take just 1 or 2 minutes to send the email to all of the addresses.

Back To Main

The Back To Main button returns you to the main uDirectoryTM control panel.


10. Viewing Listings

All .html pages that are generated by uDirectoryTM will be located in the directory that you specified in questions 3 and 4 of the script setup. These are the pages that visitors to your web site will see. This section describes how to link to the listing pages, use the goto navigation fields to view different categories, and how to search the listings.

Linking To The Listings

To allow visitors to your web site to view your listings, you will want to add hyper-links on your web site to the listings. There are many ways to do this, so here are just a couple ideas:

Allowing Visitors to Add/Edit Listings

If you want to allow visitors to your web site to add/edit their own listings, then you will need to add the following links to your web site:
Note 1: The above add/edit links will only work if you enabled visitor editing in question #8 in the Configuring The Script section.

Note 2: You can see another example of how to add these links by taking a look at the HTML of the example_index_page1.html that was include with uDirectory.

Viewing Different Categories

uDirectoryTM makes it easy for visitors to view different categories. All visitors have do is select the desired category from the navigation box at the top of each category page and then press the GO button.

Searching The Listings

uDirectoryTM also makes it easy for visitors to search for specific information in the listings. Visitors can use the search box that is located at the top of each category page to do searches on specific fields in specific categories. That is, just select the field you want to search on, enter the keyword to search for, and then press the Search button. An additional option allows visitors to search on the current category or on all categories.


11. Frequently Asked Questions

In order to keep our FAQ pages as up-to-date as possible, we have moved the Frequently Asked Questions information to our on-line reference site:

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


12. Troubleshooting

In order to keep our Troubleshooting pages as up-to-date as possible, we have moved the Troubleshooting pages to our on-line reference site:

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


13. Data Format and Importing Data

This section describes how and where uDirectoryTM stores the listing data. This information can be helpful when moving your listings to another site or if you wanted to setup a database to generate the data files for importing into uDirectory.