Tooltip Documentation - Part Two

Page Topics:

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

A table listing all the properties, along with description and demonstration of each, is provided to licensed users. The following lists some of the more commonly used properties.

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

If you want individual tooltips to deviate you can use the content_vars object literal[1] to specify exceptions for those properties. Read on for information.

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.',
    // 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 dw_Tooltip.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 wrapFn or positionFn or should be hoverable, etc. The following section on formatting functions gives another example.

Formatting Functions

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

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

An 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.

Ajax Tooltips

Recently updated code provides more 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 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
}

Positioning Functions - Possibilities

By default the tooltip is positioned near the link hovered over. The code provides an additional positioning function: positionWindowCenter. The code is designed to support custom positioning functions which could be written to position the tooltip in other ways as well.

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

More for Licensed

Additional documentation and examples are available for licensed users of the code. These extras include:

  • A table listing all possible entries in dw_Tooltip.defaultProps, complete with demonstration and description.
  • Combining in-page html elements as tooltips with different styles and other properties.
  • Positioning Options
  • Multiple styles for tooltips
  • Sticky Tooltip

If you have purchased a license within the past 12 months you may access the additional documentation and demos as well as download an alert-free copy of any code updates. You will need your transaction ID and invoice number to access the code, documentation and additional demos provided to licensed users.

Feel free to contact dyn-web if you are unable to locate your invoice number and transaction ID and we will try to assist you.

Back to top

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