K&L Custom Tooltips Script. Web Developer's Manual.

K&L Custom Tooltips Script enhances the presentation of the HTML title attribute that is used to display supplemental information about an element. By default the title attribute is usually presented as a single line, and only a limited amount of information can be presented. K&L Custom Tooltips Script can use longer alternative text or predefined HTML block elements for tooltip content.

Installation

K&L Custom Tooltips Script consists of the following files that come in an archived form (kltooltips.zip):

kltooltips.js (or kltooltips.evaluation.js in evaluation version): - contains the script code
kltooltips.css: - contains definitions for sample tooltips styles
klmanual.css: - contains definitions for this manual styles
kltooltipsmanual.html: - this manual

The archived folder structure is as follows:

/kltooltips/kltooltipsmanual.html
/kltooltips/scripts/kltooltips.js
/kltooltips/styles/kltooltips.css
/kltooltips/styles/klmanual.css

After the kltooltips.zip is unzipped, copy the file containing the script code (kltooltips.js or kltooltips.evaluation.js) in a folder containing scripts for your pages. The script file is attached to HTML document using script element:

<script type="text/javascript" scr="ScriptsFolder/kltooltips.js"></script>

You can copy the kltooltips.css to a folder containing your page stylesheets and modify the sample styles to fit your needs, or you can define the tooltip styles within your existing stylesheets. If you do the former, make sure the style sheet file is linked to your HTML document:

<link rel="stylesheet" media="screen" type="text/css" href="StylesFolder/kltooltips.css" />

The K&L Custom Tooltips Script is initialized by calling the function initToolTips(defaultUserOptions,addTitles,rootNodeID) from the document.body.onload event:

<body onload="initToolTips(defaultUserOptions[,addTitles,rootNodeID])">

The initToolTips function parameters are as follows:

defaultUserOptions: The string containing the default user options.
addTitles: Optional boolean value. When set to true, all elements with non-empty title attribute are converted to present their content by K&L Custom Tooltips Script. When omitted, or set to false, only elements with set tooltip or ttoptions attributes are converted. This parameter allows you to keep the default presentation of title attribute for some elements.
rootNodeID: Optional string value. When set to a valid element ID only the children of this element are used with the K&L Custom Tooltips Script. When omitted or set to an invalid ID, the entire body element is parsed and all applicable tooltip content is converted to be presented by the script. This option speeds up initialization of large pages which have siginificant portions of content that does not require tooltip functionality.

Unlike the majority of similar scripts, K&L Custom Tooltips Script does not require adding onmouseover and onmouseout event handlers to every element with tooltip content, therefore significantly reducing the document size and saving tooltips installation time.

Configuration

The appearance and behaviour of K&L Custom Tooltips is defined using an option string that uses CSS-like declarations. Each declaration consists of a property, followed by a colon (:), followed by a value. Declarations are separated by semicolons (;).

All tooltips inherit the default options programmed into the script. The default user options supplied to the initToolTips function overide the default script options. The individual tooltip options are set using the ttoptions attribute of an HTML element the tooltip is applied to. For example the script uses tooltip class for tooltip appearance. User may want to define a different class for the tooltips:

<body onload="initToolTips('style:balloonhelp',true)">

Different style may be applied to individual tooltips on the page:

<span title="Supplemental information" ttoptions="style:boldballoonhelp">

This method of option inheritance minimizes the amount of data that needs to be added to customize the appearance of tooltips. If you already have the title attributes defined and you want a uniform presentation of tooltips throughout your site, it takes three lines to add the K&L Custom Tooltips script to your page:

Attach script to your page using <script> element.
Define tooltip style selector within you style sheet.
Add tooltips initialization to your body onload event.

Defining Tooltip Content

One of the main features that is unique to K&L Custom Tooltips Script, is it's complimentary nature. It works with the existing title attribute, enhancing its presentation in browsers with enabled scripting, without affecting accessibility of document content in browsers with disabled or inadequate scripting functionality.

Most browsers present the content of the title attribute in a form of single line tooltip. This limits the amount of text used with title attribute for complementary information about the element. K&L Custom Tooltips Script presents supplemental information within an absolutely positioned block element that can contain more than one line, therefore allowing for more content. To accomodate two levels of supplemental information, the script introduces tooltip attribute that can contain extended supplemental information:

<span title="Supplemental information for default browser rendering" 
      tooltip="Extended supplemental information that is presented by K&L Custom Tooltips script">
      Span element content</span>

In addition to presenting the alternative complementary information string stored as a value of tooltip attribute, K&L Custom Tooltips Script can present predefined HTML block elements in a form of tooltip. Such blocks can contain any HTML markup valid within a block element:

<span title="Supplemental information for default browser rendering"
      ttoptions="content:element;content-element:divttsample">
      Span element content</span>
<div id="divttsample" style="display:none;">
  <h4>Tooltip Header</h4>
  <p>Supplemental information in a form of block element that will be displayed by
  K&L Custom Tooltips script.  Such block element can contain most HTML elements,
  for example a list:</p>
  <ul>
    <li>List item 1</li>
    <li>List item 2</li>
  </ul>
</div>

The following are examples of the three ways of defining K&L Custom Tooltips content:

The tooltip for this list item is defined using title attribute
The tooltip for this list item is defined using tooltip attribute
The tooltip for this list item is defined in an HTML block element

Defining Tooltip Presentation

Presentation of K&L Custom Tooltips is completely customizable via CSS class definitions. The value of the style option is set to the name of the class selector that contains the desired styling of the tooltip:

<style>
.tooltipstyle
  { position:               absolute !important;
    padding:                0.5em;
    text-align:             justify;
    font-size:              0.75em;
    border:                 solid 2px #115;
    background:             #ddf;
    display:                none;
    z-index:                100 !important;
    max-width:              30em;
  }
</style>
...
<span title="Tooltip text" ttoptions="style:tooltipstyle">
  Span element content
</span>

There are two CSS properties within the style declaration for the tooltip block that are important for proper functioning of the script. First, the position shall be set to absolute, and second, the z-index shall be set to the highest value among the page elements to ensure that the tooltip block overlaps the rest of the page content.

Multiple space-separated class names can be used for the value of tooltip style option in a same way that they are used with the class attribute of an HTML element. This allows for easy customization of a few presentational options without having to redefine the rest of them in a new class:

<style>
.tooltipboldstyle
  { font-weight:  bold;
  }
</style>
...
<span title="Tooltip text" ttoptions="style:tooltipstyle tooltipboldstyle">
  Span element content
</span>

K&L Custom Tooltips Script provides another presentational option of putting the tooltip content within a predefined HTML block element that serves as a tooltip frame. This block element is given an ID, as well as one of its child elements designated for displaying the tooltip text. These IDs separated by an exclamation mark are used as value of frame option:

K&L Productions Tool Tip

text

<style>
#tooltipFrame
  { position:               absolute;
    padding:                0px;
    width:                  25em;
    border:                 double 3px #115;
    background:             #ddf;
    z-index:                100;
    display:                none !important;
  }

#tooltipFrame h3
  { background:             #33e;
    color:                  #fff;
    border-bottom:          solid 1px #000000;
    margin:                 0px;
    padding:                0.25em;
    text-align:             center;
    font-size:              0.9em;
  }

#tooltipContent
  { font-size:              0.75em;
    text-align:             justify;
    margin:                 0px;
    padding:                0.5em;
  }
</style>
... 
<span title="Tooltip content" ttoptions="frame:tooltipFrame!tooltipContent">
  element content
</span>
...
  <div id="tooltipFrame">
    <h3>
      K&L Productions Tool Tip
    </h3> 
    <p id="tooltipContent">
      text
    </p>
  </div>
</body>

It is important that the HTML block element used as a tooltip frame is a child of the body element. The styling of this block element and its children is done via CSS as shown. The display property of this HTML block should be set to none to prevent it from being displayed on the page.

Defining Tooltip Behaviour

K&L Custom Tooltips Script provides functionality to define tooltips behaviour. There are two tooltips options that are used for that purpose, delay, and persistence. The value of delay option is a number of milliseconds the appearance of a tooltip is delayed after the mouse enters the tooltip's element:

<span title="Tooltip text" ttoptions="delay:1000">
  element text
</span>

The persistence option controls the closing behaviour of a tooltip. When the value of persistence option is a numerical value it signifies the time perion, in milliseconds, that the tooltip remains visible while the mouse pointer hovers over the tolltip's element. In the following example, the tooltip will automatically close after five seconds, or when the mouse pointer leaves the tooltip's element:

<span title="Tooltip text" ttoptions="persistence:5000">
  element text
</span>

In order to time the disappearance of tooltip with cursor leaving the tooltip's element, the persistence option is set to mouseout:

<span title="Tooltip text" ttoptions="persistence:mouseout">
  element text
</span>

The dissappearance of a tooltip can be delayed after the cursor leaves the tooltip's element by adding the numerical value of the delay in milliseconds after the mouseout keyword:

<span title="Tooltip text" ttoptions="persistence:mouseout 3000">
  element text
</span>

The last possible value of the persistence option is nexttooltip. When set, it causes the tooltip to be displayed until the next tooltip is envoked, regardless of the position of the cursor:

<span title="Tooltip text" ttoptions="persistence:nexttooltip">
  element text
</span>

K&L Custom Tooltips Script Web Developer's Manual.