Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

124 lines (116 sloc) 6.267 kb
<?xml version="1.0"?>
<entry name="tooltip" type="widget" animated-element="tooltip" widget-element="original element">
<title>Tooltip Widget</title>
<desc>Customizable, themeable tooltips, replacing native tooltips.</desc>
<longdesc>
<p>Tooltip replaces native tooltips, making them themable as well as allowing various customizations:</p>
<ul>
<li>Display other content than just the title, like inline footnotes or extra content retrieved via Ajax.</li>
<li>Customize the positioning, e.g., to center the tooltip above elements.</li>
<li>Add extra styling to customize the appearance, for warning or error fields.</li>
</ul>
<p>A fade animation is used by default to show and hide the tooltip, making the appearance a bit more organic, compared to just toggling the visiblity. This can be customized with the <a href="#option-show"><code>show</code></a> and <a href="#option-hide"><code>hide</code></a> options.</p>
<p>The <a href="#option-items"><code>items</code></a> and <a href="#option-content"><code>content</code></a> options need to stay in-sync. If you change one of them, you need to change the other.</p>
<p>In general, disabled elements do not trigger any DOM events. Therefore, it is not possible to properly control tooltips for disabled elements, since we need to listen to events to determine when to show and hide the tooltip. As a result, jQuery UI does not guarantee any level of support for tooltips attached to disabled elements. Unfortunately, this means that if you require tooltips on disabled elements, you may end up with a mixture of native tooltips and jQuery UI tooltips.</p>
</longdesc>
<note id="functional-css"/>
<added>1.9</added>
<options>
<option name="content" default="function returning the title attribute" example-value='"Awesome title!"'>
<desc>
<p>The content of the tooltip.</p>
<p><em>When changing this option, you likely need to also change the <a href="#option-items"><code>items</code></a> option.</em></p>
</desc>
<type name="Function">
<desc>A callback which can either return the content directly, or call the first argument, passing in the content, e.g., for Ajax content.</desc>
</type>
<type name="String">
<desc>A string of HTML to use for the tooltip content.</desc>
</type>
</option>
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-option-hide.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<option name="items" default="[title]" example-value='"img[alt]"'>
<desc>
<p>A selector indicating which items should show tooltips. Customize if you're using something other then the title attribute for the tooltip content, or if you need a different selector for event delegation.</p>
<p><em>When changing this option, you likely need to also change the <a href="#option-content"><code>content</code></a> option.</em></p>
</desc>
<type name="Selector" />
</option>
<option name="position" default='{ my: "left top+15", at: "left bottom", collision: "flipfit" }' example-value='{ my: "left+15 center", at: "right center" }'>
<desc>
<p>Configuration for the Position utility. The <code>of</code> property defaults to the target element, but can also be overriden.</p>
<p><em>Note: In 1.9.0, the default value was <code>{ my: "left+15 center", at: "right center", collision: "flipfit" }</code>, but this was changed to more closely match native tooltip positioning.</em></p>
</desc>
<type name="Object" />
</option>
<xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<option name="tooltipClass" default="null" example-value='"custom-tooltip-styling"'>
<desc>
A class to add to the widget, can be used to display various tooltip types, like warnings or errors.
<p>This may get replaced by the <a href="http://bugs.jqueryui.com/ticket/7053">classes option</a>.</p>
</desc>
<type name="String" />
</option>
<option name="track" type="Boolean" default="false" example-value="true">
<desc>
Whether the tooltip should track (follow) the mouse.
</desc>
</option>
</options>
<methods>
<method name="close">
<desc>
Closes a tooltip. This is only intended to be called for non-delegated tooltips.
</desc>
</method>
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<method name="open">
<desc>
Programmatically open a tooltip. This is only intended to be called for non-delegated tooltips.
</desc>
</method>
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<events>
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<event name="open">
<desc>
Triggered when a tooltip is shown, triggered on <code>focusin</code> or <code>mouseover</code>.
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="tooltip" type="jQuery">
<desc>The generated tooltip element.</desc>
</property>
</argument>
</event>
<event name="close">
<desc>
Triggered when a tooltip is closed, triggered on <code>focusout</code> or <code>mouseleave</code>.
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="tooltip" type="jQuery">
<desc>The generated tooltip element.</desc>
</property>
</argument>
</event>
</events>
<example>
<height>80</height>
<desc>Create a tooltip on the document, using event delegation for all elements with a title attribute.</desc>
<code><![CDATA[
$( document ).tooltip();
]]></code>
<html><![CDATA[
<p>
<a href="#" title="Anchor description">Anchor text</a>
<input title="Input help">
</p>]]></html>
</example>
<category slug="widgets"/>
</entry>
Jump to Line
Something went wrong with that request. Please try again.