|
Robert E. Boughner |
Basic Core
Command Reference
|
|
1. |
Introduction |
|
This command reference lists the
commands that are contained in the basic core module of
the coolTip utility.
This utility is based upon a similar tool-tip utility called
overLIB, but differs from it in one important aspect. coolTip is
totally object-based, which means that each popup can have
their own set of properties and that there can be more
than one popup at a time on a page.
This is accomplished by specifically including the ID of
the popup's DIV container through use of the PUID
command. If this command is not used on the command line,
the popup container defaults to ctDiv . This basic version of the coolTip utility has been rewritten so that it works only in browser versions greater than 8 that adhere to the W3C standards. There is no longer any support provided for the legacy browsers Netscape 4 and IE 4.
To
make use of these commands, you need to insert the following
line in your HEAD section.
<SCRIPT TYPE="text/javascript" SRC="cCore_basic.js"></SCRIPT>
Remember that commands are always in uppercase (case-sensitive)
and can have none or more parameter values.
Download this
module as a zip file.
There are multiple ways to customize coolTip and
using a long command line to invoke coolTip is
NOT the recommended way of calling it. The suggested method
for customizing coolTip is to use either
of the following approaches:
- Define your default variables in a separate Javascript
block, placed in the HEAD section of your page, like
this:
<SCRIPT TYPE="text/javascript">
<!--
var cd_width=300;
var cd_fgcolor='#ffffcc';
var cd_bgcolor='#666666';
//-->
</SCRIPT>
This block can come either before or after the core module is loaded. Note
this way of setting default variables is not recommended.
- The approach that is recommended is to use the ctPageDefaults routine
that is in the core module. This routine
be called by placing the following little script block
after the core module loads:
<SCRIPT TYPE="text/javascript">
<!--
ctPageDefaults(WIDTH,300,FGCOLOR,'#ffffcc',BGCOLOR,'#666666');
//-->
</SCRIPT>
You'll notice that this routine uses the same command line structure that
a call to coolTip does. It will change the default variable settings
only for the current page and must be used on each page where you want these
changes to be effective. This command could also be used in an onMouseOver or onClick event
attached to a triggering link. This is particularly useful for those parameters
that behave like toggle switches because now you can effectively toggle that
behavior off and on. This method and method #1 don't involve any permanent
changes in the coolTip code.
Note that it is not recommended that you try changing the
default variables in the code unless you are very comfortable
working with Javascript because their initialization in coolTip differs
greatly from how its been done previously in overLIB. |
2. |
General
Information |
|
Additional features included in
the core module include:
- The ability for coolTip to work in conjunction with
other scripts that may also be capturing mousemovements.
- A delay on mouseout. The default action is for no delay.
However, if you specify a time, in milli-seconds, in
the call to the nd( ) routine, as in nd([id], millisecs),
there will be a millisecs delay
in closing the popup. If there has been any delay scheduled
in the appearance of the popup, this action is not applied.
This behavior can affect any popup whether its a STICKY
or not. If a delay time is specified via this mechanism,
any TIMEOUT applied to an earlier popup will be terminated.
- Ability to target specific popups by specifying its
id value. This parameter is not required. If none is
specified then it defaults to ctDiv the
container that holds normal popups. Both this parameter
and the time delay mentioned previously can be given
in any order.
- mouseout/mouseoff capability. For STICKY popups, if
you specify NOCLOSE on the command line so that there
isn't any Close text, the popup can be closed
by first mousing into and then out of it. (Of course,
activating any other coolTip popup on the page will normally
close this popup. See the parameter KEEPCTD.)
If there has also been a TIMEOUT scheduled in closing
the popup, the TIMEOUT is canceled and the popup closes
when you mouseout of it. The parameter MOUSEOFF,
described below, allows this same action to be applied
to a normal STICKY popup (one which also has a close
link).
- Leading Argument
- The only absolute requirement is that
if you are supplying a string argument to a coolTip call,
it must be the first argument. In particular if no string
is being supplied to coolTip then
any of the other parameters can be supplied in any order.
Note: any HTML markup that is contained within the string
argument supplied to coolTip should
convert the characters that deliminate html tags (<...>)
to their entity references (< and > respectively).
Better yet, you should define a separate text variable
in a SCRIPT block within the HEAD section of the document
and pass that to the coolTip call. If
you do this then you don't need to replace the HTML delimiting
characters by their entity references.
This same requirement pertains to the ctPageDefaults routine. If you supply
a string argument in a call to this routine, it will become the default setting
for the cd_text variable rather than the normal 'Default
Text' string.
- Multiple popups
- coolTip is an object-based version
of overLIB and as such supports the display of more than
one popup at a time. However, in order to use this feature,
the popup ID must be specified via the PUID command.
In addition, the closing routine, nd() ,
which accepts the ID (a string value) to control the
popup to be closed . If there isn't any PUID parameter
or if it is not followed with an ID string value, then
the default ID that is used will be ctDiv.
These DIV containers will be created dynamically, if
they aren't already present, and added to the document
tree in all supported browsers. An illustration of this
behavior is given below in conjunction with the description
of the PUID parameter.
(NOTE: Also see the description of the parameter KEEPCTD.)
- onLoad Handlers
- If you assign a function to the onLoad event
associated with the BODY tag, then you need to make sure
that it is preceded by the following statement:
cLoaded=1;
... . This is required because doing so will over-ride
the window.onload value [=ctLoadHandler] that is set
in the coolTip code and which resets
the flag indicating that the coolTip code
has been downloaded.
|
3. |
Behavior, Positioning
and Sizes |
|
- STICKY
- Makes the popup stick around until closed.
Variable: cd_sticky
- WIDTH pixels
- Sets the width of the box to the size given by the value pixels,
a number. Default width is 200 pixels.
- HEIGHT length
- Sets the height of the box to the given value, a length value, which is a number followed by a length unit. If just a number, it assumed to be pixels. Default value is the null string ('').
Variable: cd_height
- CONTENTHGT length
- Sets the height of the content area to the given value, a length value, which is a number followed by a length unit. If just a number, it assumed to be pixels. The content area is the region immediately below the caption box. Default value is the null string ('').If the content in this region exceeds this value, scroll bars will appear so that the content can be seen. This parameter takes precedence over the HEIGHT parameter.
Variable: cd_contenthgt
-
- LEFT
- Makes the popups go to the left of the mouse.
Variable: cd_hpos
- RIGHT
- Makes the popups go to the right of the mouse. This is
the default horizontal position for popups.
Variable: cd_hpos
- CENTER
- Positions the mouse in the center of the popup.
Variable: cd_hpos
- ABOVE
- Makes the popups go above the mouse. Note: The HEIGHT
of the popup is automatically accounted for internally
when positioning the popup.
Variable: cd_vpos
- BELOW
- Makes the popups go below the mouse. This is the default
vertical position of popups.
Variable: cd_vpos
- OFFSETX x
- How far away from the pointer the popup will show up,
horizontally. Positive values move the popup to the right,
while negative numbers move the popup to the left, relative
to the cursor. A number whose default value is 10.
Variable: cd_offsetx
- OFFSETY y
- How far away from the pointer the popup will show up,
vertically. Positive values move the popup lower, while
negative numbers move the popup higher, relative to the
cursor. A number whose default value is 10.
Variable: cd_offsety
- AUTOSTATUS
- Sets the status bar's text to the popup's text. Overrides
STATUS.
Variable: cd_autostatus
- AUTOSTATUSCAP
- Sets the status bar's text to the popup's caption. Overrides
AUTOSTATUS and STATUS.
Variable: cd_autostatus
- SNAPX grid
- Snaps the popup to an even position in a horizontal grid.
Variable: cd_snapx
- SNAPY grid
- Snaps the popup to an even position in a vertical grid.
Variable: cd_snapy
- RELX position
- Positions the popups horizontal position, a number in
pixels, relative to the upper left hand corner of the browser
window. Overrides all other horizontal placement commands,
including FIXX. Negative values will position the popup
from the browser's right hand edge (as in this example
which positions the popup 100 pixels from the right).
Variable: cd_relx
- RELY position
- Positions the popups vertical position, a number in pixels,
relative to the upper left hand corner of the browser window.
Overrides all other vertical placement commands, including
FIXY. Negative values will position the popup from the
bottom edge of the browser window (as in this example
which positions the popup 100 pixels above the bottom
edge of the browser window).
Variable: cd_rely
- TIMEOUT millisecs
- Makes the popup go away after the requested delay, a
number. 1000 millisecs is about 1 second.
Variable: cd_timeout
- DELAY millisecs
- Makes that popup behave like a tooltip. It will popup
only after a certain delay specified in millisecs, a number.
One second is 1000 millisecs.
Variable: cd_delay
- HAUTO
- Automatically determine if the popup should be to the
left or right of the mouse. This command switches the current
state of this parameter to its opposite state. Default
value is off (0).
Variable: cd_hauto
- VAUTO
- Automatically determine if the popup should be located
above or below the mouse. This command switches the
current state of this parameter to its opposite state.
Default value is off (0). This swap occurs near the upper
and lower boundaries of the browser window if the popup
will become hidden.
Variable: cd_vauto
- CLOSECLICK
- Force users to click on "Close" to close sticky popups.
This command switches the current state of this parameter
to its opposite state. Default value is off (0) which means
that you close a sticky popup by mousing over the "Close" text.
Variable: cd_closeclick
|
4. |
Colors, Fonts and
Images |
|
- FGCOLOR color
- Color of the inside of the popup box, a string value.
Default is '#CCCCFF'.
Variable: cd_fgcolor
- BGCOLOR color
- Color of the border and caption area of the popup box,
a string value. Default is '#333399'.
Variable: cd_bgcolor
- TEXTCOLOR color
- Sets the color of the text inside the box, a string value.
Default is '#000000'.
Variable: cd_textcolor
- CAPCOLOR color
- Sets the color of the box's caption text, a string value.
Default is '#FFFFFF'.
Variable: cd_capcolor
- CLOSECOLOR color
- Sets the color of the close text, a string value. Default
is '#9999FF'.
Variable: cd_closecolor
- TEXTFONT font
- Sets the font to be used by the main text, a string value.
Default is "Verdana,Arial,Helvetica".
Variable: cd_textfont
- CAPTIONFONT font
- Sets the font of the caption, a string value. Default
is "Verdana,Arial,Helvetica".
Variable: cd_capfont
- CLOSEFONT font
- Defines the font for the "Close" text, a string value.
Default is "Verdana,Arial,Helvetica".
Variable: cd_closefont
- TEXTSIZE size
- Size of the main text's font, a number. Default is 11(px),
and the assumed length unit is pixels.
Variable: cd_textsize
- CAPTIONSIZE size
- Size of the caption's font, a number. Default is 10(px),
and the assumed length unit is pixels.
Variable: cd_captionsize
- CLOSESIZE size
- Size of the "Close" text's font, a number. Default is
9(px), and the assumed length unit is pixels.
Variable: cd_closesize
- TEXTALIGN body text alignment
- Specifies how the body text should be aligned. Permissible
values are 'left', 'center', or 'right'. The default value
is 'left'. This parameter can be specified in either lower
case or upper case letters. This is a convenience command
so that users can easily align the body text without resorting
to writing a custom class.
Variable: cd_textalign
- CAPALIGN caption text alignment
- Specifies how the caption text should be aligned. Permissible
values are 'left', 'center', or 'right'. The default value
is 'left'. This parameter can be specified in either lower
case or upper case letters. This is a convenience command
so that users can easily align the caption text without
resorting to writing a custom class.
Variable: cd_capalign
- CAPICON url
- Displays a small icon before the popup caption, a string
value giving the URL of the image. Default is the null
string (''). There
is a 5 pixel horizontal spacing around the image and it
is aligned to the middle of the text in the caption.
Variable: cd_capicon
- BORDER pixels
- Makes the border of the popups thicker or thinner, a
number. Default is 1.
Variable: cd_border
- BACKGROUND picture
- Instead of using the table box as background, your picture
will be used, a string value giving the URL for the picture.
Use with the FULLHTML command. See below. Default is the
null string ('').
Variable: cd_background
|
5. |
Miscellaneous |
|
- cInfo Object
- This object contains the core level version number, whether
this is a pre-release version, the major and minor numbers
of the release, the revision number of the release, and
the function meets(requiredCoreVersion),
which returns true if this release meets
the requiredCoreVersion number, othewise it returns false (even
when there is no parameter specified). This information
is contained in the global variable cInfo.
- CAPTION title
- Sets the caption of the popup, a string value. Default
is the null string ('').
Variable: cd_cap
- FGCLASS, BGCLASS, TEXTCLASS, CAPTIONCLASS, CLOSECLASS, DIVCLASS
- Custom classes to be used for the respective cases, string values. Default values are the null string (''). If any classes are specified by these parameters, they take precedence over normal styling given elsewhere in these notes.
Variables: cd_xxxxx
- CELLPAD normal, 5, 10,
and 20 pixels
of padding; can also have variable
padding
- Padding, in pixels, for the main body text in a popup.
Default value is 2. There can be up to four additional
values following this command. If there is more than one
value, then their interpretation will follow the rules
of CSS. If four values are specified then they must be
in the order TOP, RIGHT, BOTTOM, LEFT, which is the conventional
clockwise order of CSS (see the last link above). If three
values are specified, then the first one refers to the
TOP padding, the second value is the RIGHT and LEFT padding
amounts, and the last value of the three is the BOTTOM
padding. When two values are specified, the first value
is the TOP and BOTTOM padding, while the second value is
the LEFT and RIGHT padding. With a single value, the padding
is applied equally on all sides.
Variable: cd_cellpad
- CLOSETITLE title
attribute
- Sets the text string of the TITLE attribute on the close
event if CLOSECLICK is 1. Default value is "Click
to Close". If you don't want any TITLE to show, then
set this variable to the null string.
Variable: cd_closetitle
- CLOSETEXT text
- Replaces the text "Close" with something else, a string
value.
Variable: cd_close
- CLOSEIMG example
- Specifies an image to be used for closing a STICKY popup, a string value giving the relative path to the image from where the file is located. If this parameter value is not a null string, it is used in preference to the closetext above. Default value is the null string ('').
Variable: cd_closeimg
- DONOTHING example
- As the name implies, this command does absolutely nothing
at all. It was introduced because it was a feature requested
by an experienced user in order to make programming
shell wrapper functions easier. There is no variable associated with this command.
- FOLLOWMOUSE example
- Sets whether the popup should follow the cursor. Default
is true (1). When used on the command line, it will switch
the current state of the associated default variable to
the opposite state.
Variable: cd_followmouse
- KEEPCTD switch
- Normally, each call to coolTip() causes
the ctDiv container to be hidden if it's visible.
This parameter controls this behavior of the ctDiv container.
Its default value is off (0) so that the normal action
indicated above occurs. When used on the command line,
it causes the default state of the associated variable
to be switched to its opposite state. (NOTE: this parameter
name stands for keep CoolTipDiv.)
Variable: cd_keepctd
- PUID divID Using
ctDiv Using
div1
- The ID name, a string value, to be assigned to the DIV
container that will hold a popup's content. divID must
be unique on the page. If no value is assigned to PUID
for a popup, then it defaults to ctDivX, the ID
for the primary popup and X is a unique value beginning with 1. NOTE: the parameter PUID must
be specified if
you're using a secondary popup. If there
is more than one level of popup, then the parameter value
following PUID must be given. Any DIV container not present
on the page will be created dynamically.
Variable: cd_puid
- NOCLOSE
- Doesn't display the text "Close" on stickies with caption.
When used on the command line, it will set event handlers
so that you can close your popup by mousing over it and
then off of it [see the following command]. This will also
cancel any TIMEOUT that has been scheduled for your popup.
Variable: cd_close
- MOUSEOFF example example (with
1 sec delay)
- Will apply the same event handlers that are applied when
using the NOCLOSE parameter to a sticky popup that may
also have a "Close" text. Default is off (0).
When used on the command line, it will switch the current
state of the associated default variable to its opposite
state. This feature is disabled if the coolTip popup and
source code are in different frames or windows.
The MOUSEOFF command also accepts an optional parameter, which specifies
the delay in closing the popup (in milli-seconds) when a user mouse's off of
the popup so that he/she can return to click on any specified links that were
in the popup. It is used like this: coolTip(..., MOUSEOFF,
1000, ...). Like the TIMEOUT command, any delay that is specified with
this command is cancelled when mousing back onto the popup and becomes reactivated
when mousing off of the popup again.
Variable: cd_mouseoff
- FUNCTION functionname
- Calls the specified function and takes the return value
as the text that should be displayed in the popup. The
function is called when the coolTip command parser runs.
Variable: cd_function
This parameter can be called in one of four different ways:
1. FUNCTION showMe
2. FUNCTION showMe('ONE',
'TWO')
3. FUNCTION myFunctionCall where
myFunctionCall returns the results of "showMe('One','Two')"
4. FUNCTION noparameters
- STATUS text
- Sets the text in the browsers status bar to text, a string
value. Default is the null string (").
Variable: cd_status
- WRAP example
- Will cause the popup to be 'shrink-wrapped' around its
content so that it is no wider then is necessary. Default
value is off (0). When used on the command line it will
switch the current state of the associated default variable
to its opposite state. This command is not meant to be
used with a large amount of text. If it is and the resulting
popup width exceeds the width of the brower window, then
the popup's width is reset to the browser window width.
See also the "unofficial" Adaptive_Width plugin.
Variable: cd_wrap
|
|
|
NOTE. Items shown in a washed out color are no longer supported. |
|