Tooltips

The template includes a complete and powerful tooltip functionality, which can be used just by adding a class or through an API. This plugin also provides a contextual menu method.

Basic use

The basic use of the tooltip plugin is to replace the browser's built-in tooltips. To use it, just define a title for your element and add one of those classes either to the element or to its parent:

<p class="with-tooltip" title="This is a tooltip">
	Hover me!
</p>

<p class="with-tooltip" title="This is a tooltip" data-tooltip-options='{"classes":["anthracite-gradient"],"position":"bottom"}'>
	Hover me!
</p>

<ul class="children-tooltip">
	<li title="Tooltip for element 1">Element 1</li>
	<li title="Tooltip for element 2">Element 2</li>
	<li title="Tooltip for element 3">Element 3</li>
	<li title="Tooltip for element 4">Element 4</li>
</ul>

If the element with the tooltip does not have a title but contains only one child, the plugin will check the child element for a title then - useful for elements with a link inside!

Script use

It is easy to show a tooltip on any element with a simple call:

$(selector).tooltip('Tooltip message', { /* Options */ });

The content may be raw text, html, a jQuery selection or a function to run on the element and which should return the content. A wide range of options are available to customize the look and behavior of the tooltip. See methods/options references below for more details.

Once a tooltip is open, you can change its content just by calling the same method again. No need to specify options again, they will be pulled from the previous tooltip. If you specify options, they will erase the previous options.

// Open tooltip
$(selector).tooltip('Tooltip message', { /* Options */ });

// Change content
$(selector).tooltip('New message');

To remove a tooltip, just call:

$(selector).removeTooltip();

Note that if the tooltip content was pulled from the DOM, it will be restored when removing the tooltip, thus allowing multiple calls.

Ajax content loading

The tooltip content may be loaded using ajax: simply provide an url or a promise object returned by an $.ajax() call:

Inline options

<button class="button with-tooltip" title="Loading..." data-tooltip-options='{"ajax":"content-url.html"}'>
	Text
</button>

API, using url

$(selector).tooltip('Loading...', {
	ajax: 'content-url.html',
	ajaxOptions: {
		type: 'POST'
	},
	ajaxErrorMessage: 'Unable to load tooltip'
});

API, using promise object

$(selector).tooltip('Loading...', {
	ajax: $.ajax('content-url.html', {
		type: 'POST'
	}),
	ajaxErrorMessage: 'Unable to load tooltip'
});

The ajaxOptions and ajaxErrorMessage options are optional, see reference for more details

Tooltip menu

The tooltip plugin provides a menu functionality: when the user clicks the desired element, a tooltip is displayed with any custom content (it may be a menu or anything else), and it closes when the user clicks anywhere else.

Click me!

Markup

<button id="menu-tooltip" type="button" class="button full-width">Click me!</button>
<div id="menu-content-block">
	<select class="select multiple white-gradient easy-multiple-selection check-list" multiple>
		<option value="1">Option 1</option>
		<option value="2">Option 2</option>
		<option value="3" selected="selected">Selected option</option>
		<option value="4">Option 3</option>
	</select>
</div>

Javascript

$('#menu-tooltip').menuTooltip($('#menu-content-block').hide(), {
	classes: ['anthracite-gradient', 'with-small-padding']
});

In this example, the content is pulled from the DOM just by giving the corresponding jQuery selection to the function. It is detached from its original location, shown as it was hidden, and when the menu closes, it is re-inserted into its original location and hidden back. No complex callbacks, everything is built-in - but of course, the tooltips callbacks can be used if needed.

As for tooltips, the content may be text, html, a jQuery selection or a function to run on the element.

Menu content loading via ajax

As for tooltips, menus can load load some content using ajax, simply provide an url or a promise object:

$(selector).menuTooltip('Loading menu...', {
	ajax: 'menu-content.html'
});

Methods

$(selector).tooltip(content, options)

Display a tooltip over an element. If the page is not yet ready, delay the tooltip until it is ready.

Parameters

@var string|function|jQuery content a text or html content to display, or a function to run on the element to get the content (can be omitted, auto-detect if not defined or empty)
@var object options an object with any options for the tooltip - optional (see defaults for more details). If not set, the function will try to retrieve any option of an existing or delayed tooltip on the same element, so when changing the content of a tooltip just call the function without options

$(selector).removeTooltip(force, skipAnimation)

Remove tooltip

Parameters

@param boolean force use true to close tooltips even when the onClose/onAbort callback functions return false (optional, default: false)
@param boolean skipAnimation use true to disable the close animation (optional, default: false)

$(selector).menuTooltip(content, options, eventName)

Open a tooltip menu on click on any element

Parameters

@var string|function|jQuery content a text or html content to display, or a function to run on the element to get the content
@var object options an object with any options for the tooltip - optional (see defaults for more details)
@var string eventName the event on which to open the menu - optional (default: 'click')

Options reference

The defaults may be modified at runtime in $.fn.tooltip.defaults, and options may be passed inline using the data-tooltip-options attribute

position

Position: 'top', 'right', 'bottom' or 'left'
Type: string
Default: 'top'

spacing

Space between tooltip and the target element
Type: int
Default: 10

classes

Extra classes (colors...)
Type: array
Default: []

noPointerEvents

Prevent the tooltip from interacting with mouse
Type: boolean
Default: true

lock

When true, prevent any other tooltip to show on the same target
Type: boolean
Default: false

exclusive

When true, will close any other open exclusive tooltip before showing
Type: boolean
Default: false

animate

Animate show/hide
Type: boolean
Default: true

animateMove

Animate movement (positive value will move outwards)
Type: int
Default: 10

animateSpeed

Animate speed (time (ms) value or jQuery spped string)
Type: int|string
Default: 'fast'

delay

Delay before showing the tooltip
Type: int
Default: 0

ajax

Ajax content loading: url to load or Promise object returned by an $.ajax() call
Type: string|object
Default: null

ajaxOptions

Options for the ajax call (same as $.ajax())
Type: object
Default: {}

ajaxErrorMessage

Message to display in tooltip if ajax request fails (text or html)
Type: string
Default: 'Error while loading data'

screenPadding

Minimum distance from screen border
Type: int
Default: 10

arrowMargin

Minimum spacing of tooltip arrow from border when tooltip is moved to fit in screen
Type: int
Default: 10

removeOnMouseleave

Hide the tooltip when the mouse hovers out of the target element
Type: boolean
Default: false

removeOnBlur

Hide the tooltip when the user clicks anywhere else in the page
Type: boolean
Default: false

removeOnClick

Hide the tooltip when the user clicks on the tooltip (only works if noPointerEvents is false)
Type: boolean
Default: false

onShow

Callback on tooltip opening: function(target)
Scope: the tooltip
Type: function
Default: null

onRemove

Callback on tooltip remove: function(target)
Note: the function may return false to prevent close.
Scope: the tooltip
Type: function
Default: null

onAbort

Callback on delayed tooltip abort: function(target)
Note: the function may return false to prevent abort.
Scope: the target
Type: function
Default: null