API Methods

API Methods A full reference of API methods

The API features extensive methods for use with non-basic implementations, and relates well with the Events documentation.

.get()

Gets the current value of the specified option (represented in dot notation).

Signatures

.get(option)

option
Type: String
A string representing the configuration object's key you wish to change, in dot notation i.e. the name of the option

</div>

Dot notation

Dot notation is a specific format of String used to reference nested object attributes.

// Example tooltip configuration object
var config = {
	id: 'sampletooltip',
	content: {
		text: 'Hi. I am a sample tooltip!',
		title: 'Sample tooltip'
	}
};

// Example dot notations
api.get('id'); // Returns 'sampletooltip'
api.get('content.text'); // Returns 'My content'
api.get('content.title'); // Returns 'Sample tooltip'

.set()

Sets the value of the specified option (represented in dot notation) and updates all of the tooltip's relevant properties. An object may also be used to set multiple options at once.

Signatures

.set(option, value)

option
Type: String
A string representing the configuration object's key you wish to change, in dot notation i.e. the name of the option

value
Type: Various
A value to set the passed option name to, multiple types supported depending upon the option being set

.set(options)

options
Type: PlainObject
A map of key/value pairs, with the key representing an option in (dot notation), and its value being the value to set the option to.

Examples

// Single property
api.set('content.text', 'new content');

// Multiple properties
api.set({
	'content.title': 'New Title',
	'style.widget': true
});

.toggle()

Toggles the current visibility state of the tooltip.

Signatures

.toggle([state, event])

state (default: undefined)
Type: Boolean
A boolean representing the the visiblility state, hiding if false, showing if true. If not passed, it will invert the current visibility state.

event (default: undefined)
Type: Event
The event object, ideally passed when the method is called within an event handler.

Examples

// Will "toggle" the visiblitiy of the tooltip i.e. hiding it if currenty visible and vise-versa.
api.toggle();

// Show and hide the tooltip using boolean state value
api.toggle(true); // Show
api.toggle(false); // Hide
 
// Hide the tooltip when clicking these matched elements
$('.selector').click(function(event) {
	api.toggle(true, event); // Pass event as second parameter!
})

.show()

Helper method for calling .toggle(true).

Signatures

.show([event])

event (default: undefined)
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

.hide()

Helper method for calling .toggle(false).

Signatures

.hide([event])

event (default: undefined)
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

.disable()

Toggles the current interactive state of the tooltip i.e. whether it's disabled or not.

Signatures

.disable([state])

state (default: undefined)
Type: Boolean
A boolean representing the the disabled state i.e. `true` disables it, `false` enables it. If not passed, it will invert the current visibility state

Examples

// Disable the tooltip
api.disable(true);

// Enable it again
api.disable(false);

Notes

• When disabled, the tooltip will not respond to any DOM events

.enable()

Helper method for calling .disable(false).

.reposition()

Updates the tooltip's position relative to the position.target element.

Signatures

.reposition([event, effect])

event
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

effect
Type: Boolean
A boolean representing whether to animate into position using the [position.effect](./Position#effect) (`true`), or reposition immediately (`false`).

Examples

api.reposition(); // Animate into new position
api.reposition(null, false); // Reposition without animation

// Reposition the tooltip when we mouseover specific elements
$('.selector').mouseover(function(event) {
	api.reposition(event); // Pass event object!
});

.focus()

Focuses the tooltip by moving it above all others in the z-index stack. This is the functional equivalent of focusing a window on your desktop, raising it above all others whilst preserving the stacking order.

Signatures

.focus([event])

event
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

Examples

api.focus(); // Focus the tooltip manually

// Focus the tooltip when we click specific elements
$('.selector').click(function(event) {
	api.focus(event); // Pass event object!
});

Notes

• This function triggers a tooltipblur event on the currently focused tooltip (the one highest in the z-index stack).

.blur()

Blurs the tooltip i.e. removes the focus class and triggers the tooltipblur event on the tooltip.

Signatures

.blur([event])

event
Type: Event
The event object that caused the method call. Ideally passed when the method is called within an event handler.

Examples

api.blur(); // Blur the tooltip manually

// Blur the tooltip when we click specific elements
$('.selector').click(function(event) {
	api.blur(event); // Pass event object!
});

.destroy()

Completely removes the tooltip from the page, including all related event handlers and rendered DOM elements, freeing up used memory.

Signatures

.destroy([immediate])

immediate (default: false)
Type: Boolean
A boolean indicating whether or not to call `.hide()` first, allowing hide effect to be shown before destroying it.

Examples

api.destroy(); // Destroy the tooltip, animating out nicely first
api.destroy(true); // Destroy immediately without hide effect