Subversion Repositories Applications.papyrus

$Id: README,v 1.1 2007-03-16 12:39:35 jp_milcent Exp $

Project: DOM Tooltip
Maintainer:  Dan Allen (Mojavelinux) <dan.allen@mojavelinux.com>
Contributors:
        Josh Gross (JPortalHome) <josh@jportalhome.com>
        Jason Rust (CodeJanitor) <jason@rustyparts.com>
License: Apache 2.0

What is it?
-----------
This javascript library will allow you to have dynamic and configurable
tooltips on your html pages. There are several other tooltip libraries on the
web, but you will find that this library is very complete and stable.  It
includes support for all the modern browsers and behaves in a consistent way
across these platforms.  This library does not support Netscape 4. Netscape 4
is no longer an acceptable browser and it is time to move forward. That is why
I prefixed the project title with DOM. If your browser doesn't support the DOM
standard, then this library won't work.

How does it work?
-----------------
This library supports Gecko (Mozilla/Netscape6+,Firefox, etc), IE 5.5+, IE on
Mac, Safari, Konqueror and Opera 7 (which includes full DOM and CSS2 support).
The tooltips are configured through class definitions in your stylesheet and
the rest is up to javascript. The tooltips may consist of two parts, the
caption and the content. The caption is optional. The tips can either be
greasy, sticky, or velcro.  Greasy means that they move around when you move
the mouse around and go away when you leave the element. Sticky means that they
stick around after you leave the element and are otherwise stationary.  Velcro
tips disappear after a mouseout occurs on the tip itself. The tooltips also
have directionality, so you can have tips that are 'northeast', 'northwest',
'southeast' or 'southwest' of the mouse.

Be sure to include the file 'domLib.js' whereever you use 'domTT.js' and if you
want to have draggable tips or opacity fading, include the 'domTT_drag.js' and
'fadomatic.js' files as well. **Some of these libraries are available under the
domLib project.**  Please see the HOWTO.html for details on how to use the
library and the options that are available.

Why is this program so big?
---------------------------
Partly because it is feature rich and thus there is lots of code, partly
because we try to use comments where ever necessary to clarify issues, and
partly because our coding style is one which makes liberal use of whitespace.
However, to save your users the trouble of downloading 50k of JavaScript every
time they come to your page you can use Douglas Crockford's excellent jsmin
program to strip all non-essentials from the code, reducing it's size by as
much as 50%.  This program has been verified to work with his program, located at:
http://www.crockford.com/javascript/jsmin.html  
An example usage would be: 
bash# ./jsmin domTT.js domTT_min.js \
"domTT is Copyright Dan Allen (dan.allen@mojavelinux.com) (2002 - 2005).  Licensed under the Apache 2.0 license"

Anything I should know?
-----------------------
Additionally, this tooltip library autodetects select boxes in IE and the
scrollbar on multiple selects in mozilla (the only issue mozilla has) and
HIDES them whenever the tooltip collides with them.  Hence, it has full
collision detection with components which cannot use the zIndex propery!!

In order for it to work correctly you'll want to follow the example stylesheet
pretty closely.  It has been crafted to work well on all the supported
browsers.  Note the body { margin: 0; } style which is needed if you want it to
work decently on Mac IE and Opera.  (According the W3C standard, a body cannot
have a margin anyway).

By default, the library accounts for the size of the mouse when the tip is
in one of the two southern positions.  If you need to turn off this correction
on a given tip, set the option 'clearMouse' to false.  If the size of the mouse
needs to be adjusted, overwrite the global variable domTT_mouseHeight.

In 0.7.1, the hiding of flash animations was added for those browsers that
cannot put html over top of flash.  However, there are a couple of
requirements.  First, the syntax that must be used is:

<object
   type="application/x-shockwave-flash"
   data="animation.swf"
   width="450px"
   height="250px"
   pluginspage="http://www.macromedia.com/go/getflashplayer">
   <param name="movie" value="animation.swf" />
   <param name="wmode" value="opaque" />
   ...alternate (non-flash) html here!...
</object>

If you use the object+embed syntax, the flash will not be properly detected.
The second requirement is that the flash must be included in an element with a
position of either absolute or relative.  If it is not, the flash animation
will be relocated in the DOM and therefore will not be aware of its location on
the page, making collision detection worthless.

Why did you write it?
---------------------
The reason I wrote this library is because I wanted a library which used 100%
DOM to do the tooltips, was easy to configure, was fast, and which was freely
distributable.  You may use this library in personal or company, open source or
proprietry projects.  I wrote it for you, so enjoy it.  All I ask is that you
spread the word and please give me credit by leaving in my comments.  If you
do make patches, please let me know about them on my forums.  Viva Open Source!!

Important Changes in 0.7.1
--------------------------
Fading library is now fadomatic.js, so be sure to change your include
when using the fade feature.  This is a third party library developed
by fadomatic@chimpen.com.  You can find this library at the following URL:

  http://chimpen.com/fadomatic

The global setting domTT_classPrefix was changed to domTT_styleClass and the
equivalent options without the domTT_ prefix in the domTT_activate() function
call have been changed.

Important Changes in 0.70
-----------------------------
IE 5.0 is no longer supported because its DOM implementation is just too
crippled.  Many of the complaints about the positioning of the tips and
the screen edge detecting are now fixed.

Important API Changes in 0.60
------------------------------
The release is 0.60 and it introduced several significant changes over the
0.55 release.  Several of the options have changed names.  The following is a
list:

'status' -> 'statusText'
'close'  -> 'closeAction'
'prefix' -> 'classPrefix'
'id'     -> *no longer an option*

There is also a new option 'trail' which is used in place of mousemove.  Do not
use domTT_activate() in the onmousemove event handler any longer!!!  It was far
too slow to parse the same options all over again from onmouseover, so now just
specify the domTT_activate() in onmouseover with the option trail.

Also to note, the functions domTT_true() and domTT_false() have been changed to
makeTrue() and makeFalse() respectively to make them more understandable.

Be sure to include the file 'domLib.js' whereever you use 'domTT.js'
and if you want to have draggable tips or opacity fading, include the
'domTT_drag.js' and 'fadomatic.js' files as well.