Web Auction Readme File
Last Modified December 14, 1999

Web Auction Release Version 1.1                                   
Copyright 1999 David Turley <dturley@pobox.com> This program is free
software. You may modify and distribute it under the same terms as perl
itself. 


Web Auction A Web-based auction program written in Perl by David Turley
Copyright 1999

This file explains how to set up your auction. Please read this file
carefully. The auction is easy to set up, but following the directions
will save you time and effort.

INTRODUCTION

The archive file auction.tar contains the files you need. The archive
consists of the following files:

admin.txt - The administrator password file.
auction.cfg - The configuration file.
auction.cgi - The main auction script.
auction_admin.cgi - The auction administration script.
auction_reg.cgi - The user registration script.
auction-lib.pl - A library file used by the three above scripts.
readme.txt - This file.

The auction is easy to set up and will run almost "out of the box." It
requires Perl 5.005 at least running under Unix or Linux. Support for
Windows servers is no longer maintained. I don't run Windows so I am not
inclined to support that OS.

I suggest you set up the auction with the default setup, and later
customize it to suit your Web design preferences. If you need directions
for running Perl CGI scripts on your Web server, you should check with
your ISP or system administrator for instructions.


SETUP

The first thing you should do is create a directory on your Web site to hold the
auction data files. The instructions that follow assume you call this directory 'info'.
Upload the file 'admin.txt' to this directory. Since this directory will contain
the auction data and user registration information, you should password protect
this directory. Under Unix, you can use htaccess. Next, upload the remaining
files, auction.cfg, auction.cgi, auction_admin.cgi, auction_reg.cgi, and
auction-lib.pl, into your CGI script directory. This is usually a directory
called 'cgi-bin'. Make the three .cgi files executable. On most servers the
permissions should be set to 755. If required on your server, you may rename the
three .cgi files to .pl files.

You might need to edit these lines as well:
use lib qw(/web/cgi-bin);
require 'auction-lib.pl';

Now edit the first line of the three .cgi files to reflect the path to Perl on
your server. Next, you must edit 'auction.cfg'. This file contains the global
configuration settings for the auction and is explained in detail below.

AUCTION.CFG EDITS

The configuration variables in this file determine global settings for
your auction. The file is designed to be simple to edit, do not treat it
as Perl script; the values are not enclosed in quotes and there are no
line ending colons. Use the values that are already entered as clues as
to what the values should be on your server.

The values are defined as follows:

INFO_PATH - This is the system path to the info directory you created
above. Be sure to include the trailing slash. Use the complete path, not
a relative path. You can determine this path from the command prompt by
cd'ing to the info directory and typing the `pwd` command.

AUCTION_URL - This is the URL to the auction main page. This is either the URL to
auction.cgi, or the URL to the custom main auction page that you created.
Instructions are included below for creating your own auction page that lists the
categories. For now, use the script created page.

REGISTER_URL - This is the URL to the register.cgi script.

TIME_TYPE - This setting determines how time is displayed on your
auction. Set this to 1 to use a 12-hour clock, with AM and PM
designations. Setting this value to 0 will create a 24-hour clock.

MAIL_FROM - This is the return email address that the auction uses when
sending mail.

MAIL_SERVER - This is the path to the sendmail binary on your system.

AUCTION_TITLE - This is the title of your auction. It will be used in
headings and email.

SHOW_HOURS - Auction items may be displayed with winning bids after the
bidding is closed. Set this variable to the number of _hours_ that you
wish them to be displayed. The items are moved to the history file when
bidding is finished, but will remain displayed until this time is up.
Set to 0 to disable this feature.

EXTENDED - Bidding can be extended past the pre-set closing time if
bidding is active. Set this variable to the number of _minutes_ by which
bidding should be extended. For example, if this is set to 15, when the
closing time is reached, the bidding will be closed only if there have
been no bids for 15 minutes. Bidding continues until no bids have been
placed for 15 consecutive minutes.

NOTIFY - The auction will automatically notify the winner when bidding
on an item concludes. Set this to 1 to enable this feature, set to 0 to
disable. Please note that this notification is done when the auction is
next accessed after bidding closes.

UPDATE - Email is sent to bidders when they have been outbid on an item,
inviting them to return and place another bid. Set this to 1 to enable
this feature, set to 0 to disable.

That's it. You do not need to change any other variables in auction.cfg.
In fact, you probably shouldn't. Save your edits and your auction is
ready for testing. Use the Auction Administration script as described
below to set up auction categories and items to your auction.

AUCTION ADMINISTRATION

You create your auction categories and add items to the auction by using
your Web browser. Access the administration script using the URL that
points to where you installed the script.
http://www.yourdomain.com/cgi-bin/auction_admin.cgi is an example URL.
Please be advised that you must use a browser that supports frames and
JavaScript for the administration script. You must also allow the script
to set a cookie. The cookie is deleted when you quit your browser. (The
main auction script does not use cookies.)

You will be prompted for an administrator's password. The default
password is 'password', without the quotes. Enter this password in the
space provided. After you are logged in, the first thing you should do
is change your password by clicking the 'Change Password' button. Be
sure to safely store the password, there is no way to decrypt a password
used by the auction. The auction administration functions are described
below. Please remember that all the functions that relate to auction
items use the category listed in the pull-down menu. If you are working
in one category, and wish to work in another category, don't forget to
select a new category from the menu.

'Edit Categories' You will need to add categories to your auction before
you can add items. After selecting this option you will be presented
with a form for adding categories. There are two parts to a category.
The category name is the descriptive name that your visitors will see.
It can be whatever you choose; Cars and Boats, Slugs and Stuff, Clocks,
Tools, etc. The category key is the keyword that is used by the auction.
It must be a single word, with no spaces or punctuation; cars, slugs,
clocks, tools. Choose something related to the category name to make it
easy for you to remember. All files associated with the category, such
as the log and data files, will have names based on this key.

'Add Item' This is the function that you will probably use the most.
This allows you to add items to the auction. The form fields are
explained at the top of the page, but a couple of comments are
warranted. Do not enter currency symbols when entering opening and
minimum bid amounts. The auction defaults to adding a dollar sign ($).
If you need other currencies, you'll need to edit the Perl code. The
script uses basic JavaScript to check if the dates entered are valid.
All times in the pull down menus are designated in 24-hour (military
format). How the times are displayed to your users of the auction is
determined by the TIME_TYPE setting in auction.cfg. The Item URL and
Item Description fields are optional. You should probably include a
brief one or two sentence description. You may also create individual
Web pages for the items. Be sure to enter a complete URL for these
pages. The item name on the bidding page will be a link to this URL. You
may leave these items blank if you choose not to use these features.

'Modify Item' This function will allow you to edit items you have added
in case you made a mistake or wish to change something. Select an item
from the list. The modify form has the same fields as the 'Add Item'
menu.

'Delete Item' You probably won't, or shouldn't, use this function very
often. The auction will automatically delete items from the active file
and add them to the history file when the bidding is completed. Deleting
items with the delete menu is permanent. If you delete items before they
have concluded and they have not been moved to the history files, any
bidding information will be lost. Use this function if you want to
delete items before the bidding begins. You may either delete individual
items by checking the box by the name, or delete all items in the
category at once by clicking the 'Delete All' button.

'Closed Items' The 'Closed Items' button will display the bidding
results for items that have past their ending bid times. The display
will show the Item Number, Item Name, Open and Close Times, Winner ID
and Winning Bid. The Winner ID is a link. Clicking a Winner ID will open
a window displaying the registration information for that person,
including a "mailto" link. You may also remove items from the 'Closed
Items" list using this menu.

'Export User File' This function will create a tab-delimited file of all
registered user information. You may then import this information into a
database or spreadsheet. The file will be placed in the directory
specified in INFO_PATH in the auction.cfg file. Creating the file will
overwrite any previous export files.

'Import Data File' You may use this to import a properly formatted,
tab-delimited text file containing auction items. This allows you to use
a spreadsheet to create your data files, instead of using the Web-based
functions. If you have a lot of items to add, this may be the quickest
way. The format of the data file to be imported is very important. Set
up your spreadsheet with six columns. The column contents are as
follows:

Opening Date/Time
Closing Date/Time
Opening Bid
Minimum Bid Increase
Item URL
Item Description

The format of the Date/Time columns is very important. Please note that
the month name is spelled out, the year is 4 digits, and there is no
comma in the date. You must also use a 24-clock format for the time
portion.

After you have entered the data in the spreadsheet, save the file as a
tab-delimited file. The file name you use is derived from the category
key. For example, if the category key is cars, the file must be saved as
cars_import.txt. You must create the corresponding category in the
auction before attempting to import the data file.

A sample data file line is shown next. The <tab> represents tabs stops,
and this must all appear on a single line in the data file.

Item Name<tab>January 31 1998 12:30:00<tab>January 31 1999
14:30:00<tab>250<tab>10<tab>http://www.binary.net/dturley/auction_info/item.html<tab>This
is a cool item.

Upload the import file to the directory specified in INFO_PATH. After
selecting the proper category from the menu, click the 'Import Data
File' button. Your file will be imported into that category's data file.
Check the items in the auction to be sure your import file was formatted
properly.

'Delete User' You may use this function to remove a registered user.
Select the user or users you wish to remove. Once removed, all
information for this user is deleted from the user file and they will no
longer be able to bid without re-registering.

'Add From History' This function will allow you to add finished items
back into the active auction. This is useful if an expired item did not
sell, or you have another to sell. Select the items you want re-entered.
You also must select the number of days to add to the original ending
time. The original start times will be retained. The selected items will
be removed from the closed items file, so be sure you have recorded an
bidder information first.

'Show Log' This function will show the log of all bidding for the category. The log
entries will be sorted by item, then time. Since this log will grow pretty fast,
you may delete log entries by checking the items and clicking the "Delete Log Entry"
button. Please note, the log format was changed in version 1.02. Logs created with
earlier versions cannot be viewed. 

'Change Password' Use this function to change your administrator's
password.You will need to enter the new password twice. A confirmation
screen will confirm the password change. All passwords are encrypted.
There is no way to decrypt a password so be sure to write it down
somewhere.

'Log Off' You will automatically be logged out of the administration
application when you quit your web browser. However, you may use this
button to log out if you do not wish to quit your browser, and others
have access to your computer.

WHAT'S NEXT?

Now that you have the auction set up, you will probably want to
customize it to match or site. The major change is to create a main
auction page to list the categories in your auction. The auction script
will automatically create a default page with this info that is useful
for testing but most people will want their own page, complete with
graphics.

Custom Auction Page

To create a custom auction page, you only need to provide the proper
links to the auction categories. How this is done can be seen by viewing
the HTML source of the default page created by the auction script. To
call a category you simply add it's key to the script path. For example,
the link for the cars category would be:

http://www.domain.com/cgi-bin/auction.cgi/cars

You can create your own images or buttons and link them to the categories. You
should also include a link to the registration script, and a link to the auction
rules for your site.

To make the script use your custom page instead of the default page,
enter the URL of your page in the AUCTION_URL variable in auction.cfg.
Whenever the auction writes a link to your auction page, it will use
this URL instead. In addition, if you have a custom page and the auction
script happens to get called directly, it will redirect to your custom
page instead of generating the default page.

Adding Fields to Registration Form

The auction registration script is designed to allow user to easily
added fields to the registration form. Information fields for Credit
Card information are provided, however, by default these fields have
been commented out. Follow these steps to enable the Credit Card fields:

In auction_reg.cgi, look for the lines that state "#uncomment next lines
to include credit card info in form." This will be around line 52 and
line 203. Remove the comment (#) mark from the beginning of the lines
that follow. In auction_admin.cgi, look for the line "#uncomment next
lines to include credit card info in form", around line 1270 and
uncomment the following line.

Other Changes

You may want to change the background and text colors for the auction
and registration scripts. Near the top of both auction.cgi and
auction_reg.cgi, there are variables that you can set to change the
background color, text color, link and visited link colors, and a
background image.

CONCLUSION

None yet, the saga continues. My Web auction script has taken on a life of its
own and I enjoy working on it. I will continue to make updates and improvements
as suggestions come in. I hope you find the script enjoyable and profitable.

Cheers,
David Turley
dturley@pobox.com

Disclaimer: The information, code, and advice provided here is provided as is without
warranty of any kind, either express or implied, including but not limited to the
implied warranties of merchantability and fitness for a particular purpose. In no
event shall David Turley be liable for any damages whatsoever including direct,
indirect, incidental, consequential, loss of  business profits or special damages,
even if David Turley has  been advised of the possibility of such damages. Installing
and using the  information, code, or advice indicates the user's acceptance of these
terms and conditions.



