tooltip.xml

<?xml version="1.0"?>
<entry name="tooltip" type="widget" animated-element="tooltip" widget-element="original element"
	option-hide-default="true" option-show-default="true">
	<title>Tooltip Widget</title>
	<desc>Customizable, themeable tooltips, replacing native tooltips.</desc>
	<longdesc>
		<p>Tooltip replaces native tooltips, making them themeable 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 visibility. 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>

		<h3>Keyboard interaction</h3>

		<p>When the tooltip is open and the corresponding item has focus, the following key commands are available:</p>
		<ul>
			<li><code>ESCAPE</code>: Close the tooltip.</li>
		</ul>

		<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

		<ul>
			<li>
				<code>ui-tooltip</code>: The outer container for the tooltip.
				<ul>
					<li><code>ui-tooltip-content</code>: The content of the tooltip.</li>
				</ul>
			</li>
		</ul>

		<h3>Dependencies</h3>
		<ul>
			<li><a href="/category/ui-core/">UI Core</a></li>
			<li><a href="/jQuery.widget/">Widget Factory</a></li>
			<li><a href="/position/">Position</a></li>
			<li><a href="/category/effects-core/">Effects Core</a> (optional; for use with the <a href="#option-show"><code>show</code></a> and <a href="#option-hide"><code>hide</code></a> options)</li>
		</ul>
	</longdesc>
	<note id="functional-css"/>
	<added>1.9</added>
	<options>
		<option name="classes" type="Object">
			<default>{
	"ui-tooltip": "ui-corner-all ui-widget-shadow"
}</default>
			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		</option>
		<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>
			<type name="Element">
				<desc>A DOM element to use for the tooltip content.</desc>
			</type>
			<type name="jQuery">
				<desc>A jQuery object 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 than 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>Identifies the position of the tooltip in relation to the associated target element. The <code>of</code> option defaults to the target element, but you can specify another element to position against. You can refer to the <a href="/position/">jQuery UI Position</a> utility for more details about the various options.</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"' deprecated="1.12">
			<desc>
				<p>A class to add to the widget, can be used to display various tooltip types, like warnings or errors.</p>
				<p>The <code>tooltipClass</code> option has been deprecated in favor of the <a href="#option-classes"><code>classes</code> option</a>, using the <code>ui-tooltip</code> property.</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-instance.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<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>100</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>
	<example>
		<height>100</height>
		<desc>Create an ajax tooltip</desc>
		<code><![CDATA[
	$(document).tooltip({
		content: function(setContent){
			var element = $( this );
			$.get("somefile.txt")
			.then( text => {
				setContent(text);
			})
			.catch ( (e) => {
				setContent(`${e.statusText}`);
			})
		},
		items: "a, [href]",
	});
]]></code>
		<html><![CDATA[
<p>
	<a href="#" title="Anchor description">Anchor text</a>
</p>]]></html>
	</example>
	<category slug="widgets"/>
</entry>