Documentation: jsScroll JavaScript-Controlled Text Scroller Applet

BrainCode.com's jsscroll.class applet
Version 3.0.1 Final Release
Copyright 1999, 2000 by BrainCode.com
Source: http://www.BrainCode.com

FREE for Private and Non-Profit Users...The FREE version displays a hook notice to www.BrainCode.com at start-up; otherwise it functions exactly as the purchased version, with all parameters and commands the same.

COMMERCIAL & FOR-PROFIT USERS ARE *REQUIRED* TO USE THE PURCHASED VERSION
of this applet, always quickly available at www.BrainCode.com.

The PURCHASED version has no start-up or other notices; and it starts and runs up to 30 seconds faster. We encourage those wishing to buy the applet to use the free version for trials, however, so you know what you're getting when you purchase.

Support is available for the purchase version of the applet, only, strictly via http://www.braincode.com/support
You must include your UserID with all support requests.

Please note that support is solely for questions concerning installation of your applet.  We will not write your JavaScript for you; nor do we troubleshoot JavaScript errors.

All other control of the applet is accomplished via JavaScript, as explained in subsequent sections. 

Do not copy and paste code from this page; though, of course, you may from the html in the demo html code included with this kit.

Important: Please note that you absolutely must NAME the applet for the JavaScript function to work.  If you don't name the applet, JavaScript calls can't find it.  See the JavaScript section (below) for more on this.

The Notice parameter must be present, exactly, or the applet will display an error message.  A missing notice will not stop the applet from functioning, however.

If you have the FREE version... enter FREE in the value. For example:
.....<param name="KeyCode" value="FREE">
If you have the PURCHASED version... enter your key in this value. For example:
.....<param name="KeyCode" value="AQ?/FFG1*PSU9">

For those with the purchased version, keys are automatically made for you dynamically off the BrainCode.com site. You receive clear, exact, explicit instructions on this at time of purchase, and each time that you make a key.

If you are unsure what the domain for the key is, use DOMAIN as the value in this parameter. For example:
.....<param name="KeyCode" value="DOMAIN">
and an information display in the applet will tell you the domain name needed when getting a key for the applet.

A missing KeyCode parameter will not stop the applet; though an error notice will appear.  An incorrect KeyCode parameter will present information indicating a key is needed for the domain where the applet resides.

This is the first line of text the applet will display on start-up.  Additional messages are programmed via the JavaScript jssDo( ) function.

This is the color of the text of the first message the applet will display.  Text color may be changed subsequently with the jssDo( ) function.  The default is red, #FF0000.

This is the mouseover link color of the first message the applet will display.  The text link color may be changed subsequently with the jssDo( ) function.  The default is green, #00FF00.

Java applets accept a limited number of fonts.  Use of fonts other than these may crash the applet.  Among the accepted fonts are: Dialog, Courier, TimesRoman, Helvetica, Symbol.  The default is usually Dialog.

Font style is set numerically in this applet.  Do not use style names.  There are four styles.  The default is 0, plain.  These are the acceptable parameter values:
.........................0 = plain
.........................1 = bold
.........................2 = italic
.........................3 = bold italic

This is strictly optional, but useful for fine adjustment of the vertical position of the text in the applet space. It's most frequently used with large fonts, which tend to appear a bit high in the frame.  The default value is 0; negative numbers are allowed.  Proportioning of the font is not affected.

This sets the scrolling speed of the text.  Higher values produce slower scrolling.  The default is 25.  In general this need not be set; but you may wish to adjust it for smoothest scrolling.  Negative numbers violate fundamental cosmic rules.

This sets the period of time the text will wait before it begins scrolling.  The value is in milliseconds, and the default is 1000 (that is, 1 second).

This sets the period of time the applet space will be blank (no text) between presentation of messages.  The value is in milliseconds, and the default is 10.  Setting this to around 250 is often desirable, as it gives the eye a moment to rest between messages.

You must set this value to 1 for links to work.  As the applet is frequently used only for active labels, the default value is 0 -- which deactivates any links.

This sets the text that will appear in the status bar of the browser.

This sets the initial background color of the applet.  #000000 is the default.  The background color may be subsequently changed with the JavaScript jssDo( ) function.

The Link parameter sets the link for the initial text message (above).  The Link parameter uses absolute paths, only, in full, explicit http:// format.

Subsequent text message links may be set with the jssDo( ) function (see below).

The Target parameter sets the target for the initial text message.  The Target parameter uses the same values as html for windows, for example:
....._new - opens a new window *
....._blank - also a new window *
....._self - loads in the same frame
....._top - opens in the same window

The Target parameter can also set the target a frame in a frameset.  Use the name of the frame (exactly).  If the Target is not set, the default is _top.

The Target can be set for subsequent messages with the jssDo( ) function.

[NB: * Netscape and Microsoft browsers interpret _blank and _new a little differently; try both.]
.

However, a few preparatory steps are necessary to ready your page.  Please follow these instructions with care!

(Do not copy and paste from this page; you can get relevant code snippets from the demo html provided with the kit.)

<script>
ready=false;
</script>

This sets a variable to be used in Step 2., below.

Your <body> tag should look like this:

<body onload="javascript:ready=true">

This sets the variable called ready to true, but only after the page is fully loaded.

<script>
ready=false;
message0="Whatever text you want to use for the first message"
message1="Whatever text you want to use for the second message"
message2="Whatever text you want to use for the third message"
message3="Whatever text you want to use for the fourth message"
message4="Whatever text you want to use for the fifth message"
// and so on...
</script>

In Step 2., the variable ready is set to true -- but only after the page is fully loaded.

This is then used as a "lock-out" in subsequent calls to the JavaScript function that controls the applet, jssDo( ) -- thereby preventing JavaScript errors that would occur if a call to jssDo( ) was made before the applet it is calling has had its object created by the page.

Thus, a call like this...

onmouseup="if(ready)Harry.jssDo(...your variables...)"

cannot function until the page is loaded.  This eliminates thrown JavaScript errors by waiting for the applet (named Harry, in this example) to load before allowing jssDo( ) to try to communicate with it.

In Step 3., we simply set up the messages to be used by the jssDo( ) function ahead of time, assigning each one to its own variable,  to make them easier to insert into the function.

The basic syntax of the jssDo( ) function is as follows:
.

Message
The text for the message. Usually you'll set this as a variable in the page header, in which case you leave out the single quotes around the variable name.  See the demo html on this!  If you insert the text directly, then, of course, the quotes are required.

TextColor
The color of the text for this message, #000000 format.  Use the quotes.

TextLinkColor
The mouseover color of the text for this message, #000000 format.  Use the quotes.

BackgroundColor
The applet space background color to show behind this message, #000000 format.  Use the quotes.

URL
The link to which the image will go when clicked (this must be an absolute http:// path).  Use the quotes.

Target
The window or frame in which the link will be opened (see the Target parameter, above).  Use the quotes, don't forget the underscore where applicable.
.

<applet code="jsscroll.class" NAME="Harry" WIDTH="300" HEIGHT="300">

Step 2.: Then exercise the jssDo( ) function, referenced to the applet NAME, thus:

Harry.jssDo(... your variables...)

Step 3.:  Eliminating JavaScript errors during loading (see JavaScript Page Preparation, above)

Using the ready variable assigned and set to false in the head and conditioned in the body onload=  you now "lock out" the use of the function until the page has loaded, thus:

if(ready)Harry.jssDo(...your variables...)

Step 4.:  Last, just attach the code above to an event or an anchor.

Do this exactly the same way you would any other JavaScript call.  See the supplied demo html for several examples of this.

With a bit of ingenuity, experienced JavaScript writers will immediately see many possibilities in this:  timed message sequences, attaching the applet to menu items, using it as a substitute for awkward dHTML layers, and much more.  Experiment!
.