Tooltip Documentation - Part Two

Page Topics:

This page continues the documentation for dyn-web's DHTML Tooltips. Part One of the documentation covers basic instructions and general information for implementing the code. This page provides more detailed information for controlling features and options of the code.

When you view the source code accompanying examples in the download file you will likely notice both defaultProps and content_vars in use. Documentation below provides information about the meaning of the settings and properties for use in controlling tooltip content and functionality.

Setting Default Properties

As mentioned in Part One of the documentation, you can use dw_Tooltip.defaultProps to specify that all the tooltips in your document should have particular features, such as hoverable or sticky, for example. If you want individual tooltips to deviate you can use the content_vars object literal[1] to specify exceptions for those properties, as described below.

The following table lists the possible entries in dw_Tooltip.defaultProps along with their data-type, possible values and/or description:

Property Type Possible values and description
klassstring className to be applied to tooltips
hoverableboolean Delay hide onmouseout to allow time for user to hover over tooltip. Default: false
durationinteger Delay hide onmouseout for specified amount of time in milliseconds
stickyboolean Keep tooltip visible until user clicks on close box, hits escape key or clicks on document outside of tooltip.
showCloseBoxboolean Whether a sticky tooltip should display a close box.
closeBoxImagestring Image path and file name for close box image.
boolean Tooltip follows mouse moverment over link. Default true when using positionRelEvent. Code sets false in some circumstances, e.g., when sticky or duration set, or alternate positioning algorithms used.
positionFnfunction pointer Name of the function used to position the tooltip. Default is positionRelEvent
wrapFnfunction pointer Name of the function used to format or "wrap" the tooltip content.
jumpLeftboolean Jump to the other side of the link when the tooltip touches the right edge of the window.
jumpAboveboolean Jump above the link when the tooltip touches the bottom of the window.
Leftboolean Display the tooltip left of the link
Aboveboolean Display the tooltip above the link
content_sourcestring Means of locating tooltip content. Default: content_vars. Other possible values: class_id, ajax
actuatorQualstring Means of identifying and locating tooltip actuators. Default: actuatorClass, examples use class name showTip. Other possible values: queryString, id
queryValstring Used with actuatorQual: queryString

Advanced use of dw_Tooltip.content_vars

The most basic use of content_vars is to specify content for individual tooltip links as a string:

dw_Tooltip.content_vars = {
    link1: 'Tooltip content for link 1',
    link2: 'Tooltip content for link 2 goes here.',
    ...
}

In addition to specifying the content for tooltips, content_vars can also be used to specify properties on an individual basis. Most of the properties listed in the table of default properties above can also be specified for individual tooltips.

For example, you can specify a default class to be used by most tooltips and use dw_Tooltip.content_vars to specify that a particular link should display using an alternate class:

// class to be used by most of your tooltips:
dw_Tooltip.defaultProps = {
    klass: 'tooltip'
}

dw_Tooltip.content_vars = {
    link1: 'Tooltip content for link 1',
    link2: {
        content: 'Tooltip content for the link 2 goes here.',
        // class for use by link2
        klass: 'tip2'
    }, 
    ... 
}

The default properties listed above that can be applied in content_vars to individual tooltips are: klass, hoverable, duration, sticky, followMouse, positionFn, wrapFn, jumpLeft, jumpAbove, Left, and Above.

The same approach as demonstrated above for klass would be used to specify whether individual tooltips should use a particular wrapFn or positionFn or should be hoverable, etc. You may view the JavaScript files in use for the examples on site to observe. See code for the tooltip index page, for the Images and Text demo and for the current document.

Reserved properties. Two properties that you may specify in content_vars have special purpose in the code: content and html_id. For example, if you specify a content property, that will generally be sent to the formatting function as the content for the tooltip. Note that some of the formatting functions expect a particular set of properties and would not make use of the content property. See below for more information.

An html_id property would refer to an element whose content you wish to display in the tooltip. This basically parallels the class_id value of content_source in defaultProps but allows you to specify other properties to use for individual tooltips. The use of class_id is demonstrated in an example in the download file. html_id is demonstrated in this demo.

Custom properties In addition to the built-in properites, you can include in the object literal any properties that you might find useful in formatting or positioning functions should you choose to write some for your own purposes. The formatting functions currently provided include properties for including image, text, caption, width of the tooltip, and width and height of images. Read on for more details.

Formatting Functions

The code supports the use of customizable functions for controlling the layout and formatting of tooltips. The following lists and describes those currently provided with the code in the dw_tooltip_aux.js file.

As mentioned above, you can specify a formatting function in defaultProps for use by all or most of your tooltips:

// all tooltips will use this wrapFn 
// unless content_vars specifies an alternate
dw_Tooltip.defaultProps = {
    wrapFn: dw_Tooltip.wrapToWidth,
    ... // other props
}

You can specify an alternate formatting function for a particual tooltip by including it in the content_vars entry for that tooltip:

dw_Tooltip.content_vars = {
    link1: {
        // alternate wrapFn for this link
        wrapFn: dw_Tooltip.wrapImageToWidth,
        // other properties for wrapImageToWidth
        img: 'images/mtnlake.jpg',
        w: 432, // width of image
        h: 346, // height of image
    },
    ... // other links
}

Adjust Width. You will often want to adjust the width of the tooltip according to the amount of content. The wrapToWidth function can be used as follows:

// with wrapFn: dw_Tooltip.wrapToWidth set in defaultProps: 
dw_Tooltip.content_vars = {
    link1: {
        w: 300, // width of tooltip div in pixels
        str: 'Content for the tooltip goes in str property.'
    },
    ... // other links
}

Images in Tooltip. When displaying images of different sizes in the tooltip you will likely want to adjust the width of the tooltip according to the width of the image. The wrapImageToWidth function also adjusts the height to help the browser properly position the tooltip within the available space: 

// with wrapFn: dw_Tooltip.wrapImageToWidth set in defaultProps: 
dw_Tooltip.content_vars = {
    link1: {
        img: 'images/mtnlake.jpg',
        w: 432, // width of image
        h: 346, // height of image
    },
    ... // other links
}

Images and Text. Three customizable functions are provided for displaying images and text in the tooltip: wrapImageOverText, wrapTextOverImage, and wrapTextByImage. They are all demonstrated in the images and text example. They all require img, txt, and w properties in their entry in content_vars:

// with wrapFn: dw_Tooltip.wrapTextOverImage set in defaultProps: 
dw_Tooltip.content_vars = {
    link1: {
        img: 'images/mandala2.gif',
        txt: 'Yin-Yang mandala',
        w: 160 // width for tooltip div
    },
    ... // other links
}

These functions also support an optional caption property with or without use as a sticky tooltip.

// with wrapFn: dw_Tooltip.wrapTextByImage set in defaultProps: 
dw_Tooltip.content_vars = {
    link1: {
        caption: 'A Heron',
        img: 'images/heron.gif',
        txt: 'Heron image created from a character font.',
        w: 210
    },
    ... // other links
}

Sticky Tooltips. Title bar, caption, and close box are often desired when using sticky tooltips. You can use the wrapSticky function directly as follows:

dw_Tooltip.defaultProps = {
    sticky: true,
    showCloseBox: true,
    closeBoxImage: '/images/btns/close.gif',
    wrapFn: dw_Tooltip.wrapSticky 
}

dw_Tooltip.content_vars = {
    link1: 'Content for link 1',
    link2: 'Content for link 2',
    ... // other links
}

The above presents the most basic use of a sticky tooltip, which will display with a close box using the default styles for the tipDiv. Since the wrapSticky function doesn't support width, caption or other properties, it is more often invoked through wrapToWidth or one of the image formatting functions when the sticky property is set true:

dw_Tooltip.defaultProps = {
    sticky: true,
    showCloseBox: true,
    closeBoxImage: 'images/close.gif',
    // positionWindowCenter often used for sticky tooltip
    positionFn: dw_Tooltip.positionWindowCenter
    wrapFn: dw_Tooltip.wrapImageOverText
}

dw_Tooltip.content_vars = {
    link1: {
        caption: 'Image in a Sticky Tooltip',
        img: 'images/mtnlake3.jpg',
        txt: 'Demonstrating a sticky tooltip ...',
        w: 440,
        },
    ... // other links
}

The basic use of wrapSticky is demonstrated in the default properties table above. The image in a sticky tooltip centered in the window is demonstrated in the images and text example.

Assistance in implementing these functions is provided upon request to licensed users of the code. If you need assistance in modifying these functions for your use or perhaps a new one for your particular needs, contact us for a quote.

Positioning Functions - Possibilities

By default the tooltip is positioned near the link hovered over, but the code supports custom functions to position the tooltip in any number of possible ways. Currently, the code only provides one additional positioning function: positionWindowCenter. However, the code is designed to support custom positioning functions which could be written to position the tooltip at window upper right, or in a particular column, at some fixed location, etc.

You can write your own custom positioning functions if you like, or hire us to write one for you according to your specifications.

Back to top

  1. We have prepared a brief tutorial on Object Literals for those unfamiliar with the syntax.^