James' URL Logger (EasyTracker)

Purpose  : URL clickthrough logging script
Version  : 1.1	 (28/9/2001)
Author   : James Blatchford (http://www.jard.co.uk/)


COPYRIGHT NOTICE
----------------
Copyright (c) 2001 James Blatchford, All Rights Reserved.

This script may be used and modified free of charge by anyone so long as
this copyright notice and the comments above remain intact in this and
all accompanying files. By using this script and its associated files,
you agree to indemnify James Blatchford and all other interested parties
from any liability that might arise from its use. Selling the code for this
program without prior written consent is expressly forbidden.  Obtain
permission before redistributing this script over the Internet or in any
other medium. In all cases copyright and header must remain intact in all
files. James Blatchford also requests that should you make any improvements
to this script, please be kind enough to let me know so that I may improve
this script for the rest of the people who use it.


DESCRIPTION
-----------

This script lets you track the number of times that visitors to your site
follow certain links on your web site (either internal within your own
site, or external links to other sites). This can be used to track which
external links on your site are the most popular, or to count how many
times certain files are downloaded from your page.


SETTING UP THE SCRIPT
---------------------

This script consists of four files:
- readme.txt      (this file)
- easytracker.pl   (the URL logging script)
- easytrackdisp.pl (the Admin/display page)
- track.txt       (the log file, initially empty)

Open both of the .pl scripts (easytracker.pl & easytrackdisp.pl) in any
plain text editor (such as Windows Notepad) and modify the first line of
each to point to the path to Perl on your server (e.g. #!/usr/bin/perl)
if you don't know what the proper path is, then check with your host or
server admin.

Then upload easytracker.pl, easytrackdisp.pl and track.txt to your
cgi-bin (if your server only supports the .cgi extension, just change the
names). Remember to upload them all in ASCII (text) format. If you are
using a Unix or Linux server then the two scripts (easytracker.pl and
easytrackdisp.pl) should be CHMODed to 755 and the track.txt file to 644.

(CHMOD means to change the file security permissions. In most FTP software
you should be able to right-click on the files and either Set Properties,
Set Attributes or Set Flags. In the resulting dialogue box you should be
able to change the file permissions, 755=RWXR_XR_X, 644=RW_R__R__)


HOW TO USE
----------

Install the scripts as described above. Then to track the links, change the
tracked link's URL to reference the script. This is done by prefixing the
link with the address of the tracker script then "?url=", as in the
following examples:

Change:	<A HREF="http://www.jard.co.uk">James' web site</A>
to:	<A HREF="/cgi-bin/easytracker.pl?url=http://www.jard.co.uk">James' web site</A>
or
Change:	<A HREF="http://www.dotdragnet.co.uk/forum/">visit this forum</A>
to:	<A HREF="/cgi-bin/easytracker.pl?url=http://www.dotdragnet.co.uk/forum/">visit this forum</A>

Note, if you have placed the scripts in a subdirectory of your cgi-bin,
or your CGI directory has a different name then the above address should
be changed accordingly.

To view the stats or perform admin functions, go to the following address
"http://www.yourserver.com/cgi-bin/easytrackdisp.pl" using your web browser
(change the server address to match your own server). You should now see
your accumulated clicks to date. Note that the "Clear Logfile" button will
completely clear your log and delete any current stats.

Remember that if you don't clear out your log regularly it could grow to be
a very large file over time.


ADVANCED SETUP
--------------

If you want to save your logfile to a different name, or save it in a
different directory, then you need to change the "$logfilename" variable
in both scripts to point to the new filename or directory. For example to
use a log file called "mylinktrack.log" in a subdirectory called "logs"
then you should change:

my $textfilename="track.txt";

to 

my $textfilename="logs/mylinktrack.log";

Please ensure that you change the variable in both scripts and that it is
identical in each, and remember to CHMOD the file to 644.


CONTACTS
--------

This script and many others are available both from the author's web site
at http://www.jard.co.uk/scripts/ and from the downloads section of
DotDragNet at http://www.dotdragnet.co.uk/downloads.asp

Remember to check back for future, improved versions.

If you have any problems with this script, any suggestions for future
improvements, or any other comments please either leave a message in the
DotDragNet Webbuilder forum (http://www.dotdragnet.co.uk/forum/), or
the jardScripts forum (http://www.jard.co.uk/cgi-bin/scripts/).


CHANGE LOG
----------
28/9/01	easytrackdisp.pl 1.2
	Graphing added to Per Link Totals section.
	Log file size now displayed in Totals section.
18/9/01	easytrackdisp.pl 1.1
	Added percentages to Totals section.
	Added server name to top of page, and script URL to bottom.
13/9/01 easytracker.pl 1.0a
	Fixed obscure typo bug that killed proper date sorting of days
	where date < 10. Unfortunately the bug will have saved to the log
	incorrectly for the first ten days of this month for anyone using this.
11/9/01 easytrackdisp.pl 1.0b
	Due to feedback removed logging of clicks on links in the log on the
	admin page (easytrackdisp.pl)
	Added "Top of page links" also due to user feedback.
22/8/01 easytrackdisp.pl 1.0a
	Minor HTML syntax errors amended, Admin page now validates as
	HTML 4.01 Transitional and CSS.
21/8/01	Full package v1.0 released to the web


FUTURE
------
Planned changes for future versions include:
- Use full file locking in the tracker script
- More sort options in the display script
- Options to set either a size or age limit on the log file