Tooltip Documentation - Part Two

This page continues the documentation for dyn-web's JavaScript 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 JavaScript Tooltip.

Setting Default Properties

You can use dw_Tooltip.defaultProps to specify that all the tooltips in your document should have particular features, such as hoverable or klass, for example. The following demonstrates how you would apply some commonly used default properties:

dw_Tooltip.defaultProps = {
    hoverable: true, // tooltip lingers so user can hover to click links
    supportTouch: true, // enables support for touch devices 
    klass: 'tooltip', // class to be used for tooltips
    wrapFn: dw_Tooltip.wrapToWidth // formatting function for tooltip content
}

You can also use .defaultProps to specify a positioning option or function, an alternate content source such as ajax or HTML elements, a close box image and more.

If you want particular tooltips to deviate from any of these settings you can use the content_vars object literal[1] to specify exceptions for those properties. Read on for information.

Setting Individual Properties Using .content_vars

The most basic use of .content_vars is to specify content for each tooltip:

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

In addition to specifying the content for tooltips, .content_vars can also be used to specify properties for individual tooltips. For example, you can specify a default class to be used by most tooltips and use .content_vars to specify that a particular link should display using an alternate class:

dw_Tooltip.defaultProps = {
    // class to be used by most of your tooltips
    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'
    }, 
    // more tooltips ... 
}

The same approach as demonstrated above for klass would be used to specify whether individual tooltips should use a particular formatting function (wrapFn), or positioning function (positionFn), or should be hoverable, etc. The following sections provide more examples.

Notice that when you use .content_vars to provide properties in addition to content for a particular tooltip, its entry becomes an object literal inside the .content_vars object literal. So it is important to pay attention to the syntax or errors will be generated and the code won't work. The Object Literals tutorial covers the basic syntax and provides guidance in locating errors. ^

Formatting Functions

The JavaScript Tooltip supports the use of customizable functions for controlling the layout and formatting of tooltips. The primary purpose of these formatting functions is to provide options for display of images, or images with text, including optional caption and close box. They also include width adjustment. See them demonstrated in the Images Example.

You can specify a formatting function in defaultProps for use by all or most of your tooltips:

// all tooltips will use this formatting function (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 formatting function for this link
        wrapFn: dw_Tooltip.wrapImageOverText,
        // other properties for wrapImageOverText
        img: 'images/mtnlake.jpg',
        txt: 'A mountain lake',
        w: 440 // width of tooltip div
    },
    // other links ...
}

^

Adjusting Tooltip Width. You will often want to adjust the width of the tooltip according to the amount of content. The wrapToWidth function is provided for this purpose. It can accommodate a str property or an img property depending upon whether your content is text or image. Both are demonstrated below:

// 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 here.'
    },
    link2: {
        w: 184, // width of tooltip div in pixels
        img: 'images/dot-com-btn.gif' // path and file name for image
    },
    // other links ...
}

Note that in wrapToWidth the width is applied to the tooltip div, not to the image, unlike wrapImageToWidth, which is described next.

Images in Tooltip. The wrapImageToWidth function allows you to specify both height and width for your images. This helps the browser more efficiently position the tooltip within the available space. This function can also be used to resize images, to display a smaller version of the image, for example.

// 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 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 ...
}

These functions make use of divs with img and txt classes for use in your style sheet. They are demonstrated in the images and text example and included in the pre-purchase download file. ^

Providing a Close Link. Another category of formatting functions will be called automatically when the tooltip is activated onclick, viewed on a touch device, or specified as sticky. These functions provide a close link or close box, depending upon properties you set.

By default the code will include a close link at the bottom unless you include properties to choose other options. These properties are showCloseBox and closeBoxImage. Include showCloseBox if you want either a close image or text X to appear at the top of the tooltip. If you want to use an image, include the closeBoxImage property along with path and file name:

dw_Tooltip.defaultProps = {
    supportTouch: true,
    activateOnClick: true,
    showCloseBox: true, 
    closeBoxImage: 'images/close.gif'
}

If the default close link at the bottom is applied it will be in a div which includes a close class for styling. Inline styles center this link and provide a small margin.

If you specify showCloseBox, with or without closeBoxImage, the following elements and classes are included in the function that provides the formatting:

div.topBar
Contains closeBox and (optional) caption span elements. Background color is typically applied here.
span.closeBox
Inline styles position absolute at upper right with text-align right. Also used to style linked text X when not using image.
span.caption
Use this selector to style captions to suit your design.
div.XtipContent
Contains the tooltip content. Padding is generally applied here.

An example in the download file demonstrates use of these elements and classes for styling.

It is possible to override any of the inline styles using !important. For example you could position the close box at the upper left with the following:

span.closeBox {
    right:auto !important; left:0 !important;
    }

If you include a caption when no close box is needed, it will be enclosed in a div with a caption class rather than in a span element. ^

Problems with close box styles? The close box can either be positioned or floated. Sometimes one approach works better than the other. Positioning can sometimes result in the close box being superimposed over tooltip content. Float, when used with captions, can sometimes result in the close box displaying slightly outside the confines of the tooltip. Both of these problems are easily overcome using styles.

Positioning is the preferable approach if you are including captions or if you are providing some background color and filling in space equal to the height of the background image at the top.

If you are not including a caption and don't wish to provide extra space and perhaps a background color at the top of the tooltip, perhaps float would be preferable for your situation. You can override the inline styles included in the code to use float as follows:

div#tipDiv span.closeBox {
    position:static !important;
    right:auto !important;
    top:auto !important;
    float:right; width:1em;
    }

Positioning Options

As demonstrated and discussed elsewhere, the tooltip code provides a wide range of options for positioning the tooltip. The tooltip can be positioned relative to the event or the target, with options for further control in either case (above, below, left, right). Positioning in the center of the window is also an option.

By default, the tooltip is positioned relative to the mouseover (or touch, click or focus) event, slightly down and to the right, with customizable offsets (offX and offY). If you prefer that the tooltip be positioned to the left or above the event you can specify this using Above and/or Left properties. For example, to position your tooltips above the event, specify this in dw_Tooltip.defaultProps as follows:

dw_Tooltip.defaultProps = {
    Above: true
}

When you are positioning the tooltip relative to the event location, the code performs calculations to keep the tooltip from either going outside the window or covering the event location, which can lead to tooltip flickering. By default the code will jump above or to the left of the event to avoid these scenarios.

One or both of the properties involved, jumpAbove and jumpLeft, can be set false if you prefer. Then the tooltip will be positioned at the edge of the window instead of jumping to the other side of the event location. If you would rather have the tooltip display at the edge of the window rather than jump above the event location, you can specify this as follows:

dw_Tooltip.defaultProps = {
    jumpAbove: false
}

Note: If both jumpAbove and jumpLeft are set false, the tooltip may be displayed partially outside the window edges. ^

Alternative Positioning Functions

As stated above, the tooltip is typically positioned relative to the event location, but the code also provides alternate positioning functions. The following functions will position the tooltip either in the center of the window or relative to the target:

posWinCenter
Positions the tooltip in the center of the window.
posCenterAboveTgt
Positions the tooltip relative to the target centered above it.
posCenterBelowTgt
Positions the tooltip relative to the target centered below it.
posLeftTgt
Positions the tooltip left of the target.
posRightTgt
Positions the tooltip right of the target.

To specify that all the tooltips in a given document use a particular positioning function, set the positionFn property in dw_Tooltip.defaultProps:

dw_Tooltip.defaultProps = {
    positionFn: dw_Tooltip.posCenterAboveTgt
}

Positioning Options for Individual Tooltips

It is also possible to specify different positioning properties and positioning functions for individual tooltips. This is done the same way as shown above for the formatting functions, using .content_vars.

In addition to these options, the code is designed to support custom positioning functions which could be written to position the tooltip in other ways as well. ^

Ajax Tooltips

An Ajax addon to the tooltip code provides flexible support for ajax tooltips, as demonstrated and described here. This download file contains example ajax tooltip implementations, along with the small external JavaScript file needed for the code.

If you are using Ajax to retrieve content for any of the tooltips on the page, specify the following in defaultProps:

dw_Tooltip.defaultProps = {
    content_source: 'ajax'
}

Request URL(s). If all of your ajax tooltips will direct their request to the same file you can specify that url as follows

dw_Tooltip.Ajax.reqURL = 'lookup.php';

If different files on the server will be used for the ajax requests, you can specify a url property in content_vars for each tooltip:

dw_Tooltip.content_vars = {
    link1: {
        // path and file name for ajax request
        url: 'file1.txt'
    },
    link2: {
        url: 'file2.txt'
    },
    // ... for more links
}

Request Parameters. You can send one or more name/value pairs of your choice with your ajax requests using a params property:

dw_Tooltip.content_vars = {
    link1: {
        // name/value pair(s) to send in ajax request
        params: { 
            cat: 'widgetX',
            prodID: 'X1111'
        }
    },
    link2: {
        params: { 
            cat: 'widgetY',
            prodID: 'Y2222'
        }
    },
    // ... more
}

These values could be used for a database query. ^

Back to top


  1. See our tutorial on Object Literals if you are unfamiliar with the syntax.^