JavaCounter and SuperClock installation and use instructions.

JavaCounter and SuperClock are Copyright 1997, P. Lutus - http://www.arachnoid.com.

The standard package includes these files:

installation.doc (this file)

For JavaCounter:

counter.class
segNums.class
jcount.cgi

For SuperClock:

clock.class
complxnum.class
clockframe.class

JavaCounter Installation

NOTE: This installation is not for the faint of heart. It requires knowledge of UNIX and Internet server technology.

The JavaCounter class file (counter.class) and the perl script jcount.cgi should be placed in a separate directory (if possible). Let's say for this example that we have named our directory "counter" (it can be given any name).

Simple Installation (relatively speaking)

Place the three counter files (counter.class, segNums.class, jcount.cgi) in the counter directory you have created. In the simple installation, you don't have to acquire graphic files for digits. Instead, you can use text mode or the built-in character generator for a digital-clock display style. 

If you plan to use the counter features of JavaCounter, create a single subdirectory to your counter directory. Name this subdirectory "data." Now skip ahead to the "operation" instructions.

Advanced Installation

Make two subdirectories to your counter directory - "digits" and "data."

The data directory will contain the automatically created counter files, one for each file and/or user.

The digits directory will contain the character sets in subdirectories with letters of the alphabet for names.

NOTE: The digit files are optional -- you can use the counter's text mode or internally generated digits instead. The setup is much simpler. More on this choice below.

But I digress. Browse the Web and acquire some character sets. Character sets with numbers 0-9 are OK for hit counting, but for clock displays you need to have colon, am and pm characters.

Most character sets will require unZIPping and renaming for use with JavaCounter. Create a subdirectory under the "digits" directory for each character set, make the name a single letter of the alphabet, and make the letter uppercase (an exception to the general rule that directory and file names should be in lowercase on UNIX server systems).

Rename the digit files and give them these names: "zero.gif", "one.gif" through "nine.gif", and "colon.gif", "am.gif", and "pm.gif" if your character set has these clock-display characters.

Or, if you are lazy (as I am) and you are downloading a bunch of different sets, use the following batch file (Windows/DOS) to automate the process. This batch file assumes that the file's first character is the digit it represents (this is true for the sets at DigitMania - www.digitmania.holowww.com):

@echo off
if not exist 0*.gif goto error
rename p*.gif pm.gif
rename a*.gif am.gif
rename c*.gif colon.gif
rename 0*.gif zero.gif
rename 1*.gif one.gif
rename 2*.gif two.gif
rename 3*.gif three.gif
rename 4*.gif four.gif
rename 5*.gif five.gif
rename 6*.gif six.gif
rename 7*.gif seven.gif
rename 8*.gif eight.gif
rename 9*.gif nine.gif
goto end
:error
echo no .GIF digit files found.
:end

Just copy this block of text into a new file and save it as (for example) "renamegif.bat." Run it in the directory where the digits are located.

At this stage we should have created a counter directory, placed the files counter.class and jcount.cgi in it, created two subdirectories "data" and "digits" and placed one or more character sets in lettered subdirectories under "digits."

Operation

Now we can test the counter. Upload the entire "counter" directory tree to your Web server and put it in a convenient location. Make sure that the Perl script "jcount.cgi" correctly identifies the location of the system's Perl interpreter.

In your test page, make an HTML tag that looks like this:

Example 1: Simple clock

<applet
codebase=(relative path to "counter" directory. See below) 
code=counter.class
name=counter
width=96
height=21>
<param name="clock" value="ampm">
</applet>

There are many options listed below for clock displays.

Example 2: Simple Counter

<applet
codebase=(relative path to "counter" directory. See below) 
code=counter.class
name=counter
width=96
height=21>
<param name="counter" value="counter_file_name">
<param name="style" value="a">
</applet>

The "width" and "height" values should be changed, depending on the size of your characters and the number of digits on display.

The "codepage" tag is not necessary if the calling page is located in the same directory as the class files.

The "style" value is the name of the letter subdirectory where the desired character set is located. The counter file name will be created in the "data" subdirectory if it does not exist, and this file will contain the current count. If you decide not to use graphic digits, simply leave off the "style" tag, and JavaCounter will revert to using its own internal character generator.

When JavaCounter is used as a page counter, a subdirectory named "data" must exist for the counter files.

There are a number of additional option parameters:

All modes

Parameter (use lowercase)
Default setting
Meaning
 Minsize
6
Minimum size of digital display, pads with zeros to set this size.
Oneclick
Message
Message visitors see when they click the counter once.
Twoclicks
Destination
URL of destination to take the visitor to when he clicks twice.
Clock
Undefined
"ampm" for 12 hour display, "24" for military style. Disables counting functions.
Timezone
Undefined
Enter an hour time zone to change to that zone, otherwise local time. Range: -12 to 12.
Count
Undefined
Enter a specific count for demonstration purposes -- does not increment a counter file.
Cgiscript
Jcount.cgi
Path and name to counter Perl CGI script.
Bgcolor
#000000
Background color for counter applet

Text Mode

Parameter (use lowercase)
Default setting
Meaning
Textmode
False
if true, chooses text-generated numbers (very simple, no graphic digits required)
Fontcolor
#ff0000
Font color for text mode 
Fontname
Courier
One of Courier, TimesRoman, Helvetica, Dialog, DialogInput. Must be entered in mixed case as shown here.
Fontsize
20
Font size for text mode
Fontmargin
5
Internal margin for font display
Fontbold
False
Use bold style of chosen font
Fontitalic
False
Use italic style of chosen font
Shadowoffset
0
Offset in pixels for shadow behind text. If 0, no shadow is drawn.
Shadowcolor
#000000
Black





Internal Digits Mode

To use this mode, simply do not define a style specification (style="letter") and don't turn on text mode (above). The digits are internally generated digital clock-style numbers that save download time over using graphics for this purpose.

Parameter (use lowercase)
Default setting
Meaning
Digitscale
1
at scale 1, the internal digits are 16 x 21 pixels. An integer value is required.
Fancy
True
fancy digits have more shading and look very much like a digital clock.
Fontcolor
#ff0000
font color for internal digits mode.
Hicolor
Undefined
this choice gives you more control of the default "fancy" mode - it is the color of the brightest parts of the digits. If this option is not set, an automatic highlight computation is performed, based on the "fontcolor" choice.


Experiment with these options. The "oneclick" and "twoclicks" options are particularly interesting, because the message "oneclick" provides appears on the browser's status line, and the visitor is taken to the "twoclicks" destination URL when he clicks twice.

Troubleshooting the Counter Perl Script

I have gotten a LOT of e-mail from people having trouble making the counter work. So here is a brief list of requirements.

The Perl counter script requires many kinds of server resources, and must be run on a Web server that is CGI-enabled. Beyond this, installation requires that many conditions be met, including, but not limited to:

1. You must place the CGI file in the correct directory, 
2. You must mark it as world-accessible and world-executable,
3. There must be a working Perl interpreter in the system,
4. The location of the Perl interpreter must correspond to the first line of the CGI script, or
5. The first line of the script must be edited to reflect the actual location of the Perl interpreter,
6. The counter system can only work on a server machine, not on your home machine unless you have a server and a Perl interpreter running,
7. Your ISP must allow CGI,
8. The directory in which the CGI script appears must be CGI-enabled,
9. The counter data directory must be read-write world-accessible.

Most of these requirements can be met only if you have a reasonable knowledge of UNIX and your ISP allows you to directly access your site directory, create directories and so forth. There are other, less likely things that can go wrong, but this list contains the most frequent problem areas.

Because of the number of possible server configurations, and because of the number of possible user skill levels, I cannot provide individual assistance installing the counter.


SuperClock Installation

SuperClock is easier to install and use than JavaCounter, because (1) it is self-contained, requiring no character sets, and (2) it doesn't require the cooperation of a Perl script.

Simply place the three SuperClock class files (clock.class, complxnum.class, clockframe.class) in any convenient location and make your "codebase" value point to that location. Here is an example.

Let's say you create a subdirectory called "clock" and install the clock files there. Most of your pages are located in the main directory "above" this subdirectory. You would create an applet tag like this:

<applet
codebase=clock
    code=clock.class
    name=clock
    width=200
    height=200 >
<param name="timezone" value="0">
<param name="bcolor" value="#c0c0ff">
<param name="shadowoffset" value="12">
</applet>

In this example, I have included three optional parameter tags, although none are required to run the clock in its default mode. The "timezone" parameter is set to 0, meaning GMT (London time). You may enter any timezone hour you require, including fractional hours for those places that require them (example: 6.5).

Here are all the options for SuperClock:

Parameter (use lowercase)
Default setting
Meaning
TimeZone
System
Sets special time zone: -12 to 12 hours inc. half-hours
ShadowColor
Black
Sets color of shadow behind objects
BColor
White
Sets color of background
SmallMarkColor
Red
Sets color of small dial marks
BigMarkColor
Blue
Sets color of big dial marks
HourColor
#204020
The color of the hour hand
MinuteColor
#4040ff
The color of the minute hand
SecondColor
Red
The color of the second hand
ShadowOffset
8
Relative shadow offset units (changes with clock size)
DigitalTime
True
Show digital time display at bottom of analog display
DigitColor
Black
The color of the optional digital display
DigitBColor
#e0e0e0
Background color for digital time display area
Ampm
True
If false show 24 hour digital time display
FontSize
12
Font size for digital display
FontName
TimesRoman
Font name for digital display
Noclicks
Message
message for no clicks
Oneclick
Message
message for one click
Twoclicks
URL
destination site for two clicks


Notice that, unlike JavaCounter, you may enter common colors by name, or any color by using the HTML color tag convention.

If you change Superclock's size with the applet tag width and height specifications, the entire clock display will scale up or down accordingly.


