Permalink
Fetching contributors…
Cannot retrieve contributors at this time
333 lines (323 sloc) 16.8 KB
<?xml version="1.0"?>
<entry name="tabs" type="widget" animated-element="panel" widget-element="tabs container">
<title>Tabs Widget</title>
<desc>A single content area with multiple panels, each associated with a header in a list.</desc>
<longdesc>
<p>Tabs are generally used to break content into multiple sections that can be swapped to save space, much like an accordion.</p>
<p>Tabs have a particular set of markup that must be used in order for them to work properly:</p>
<ul>
<li>The tabs themselves must be in either an ordered (<code>&lt;ol></code>) or unordered (<code>&lt;ul></code>) list</li>
<li>Each tab "title" must be inside of a list item (<code>&lt;li></code>) and wrapped by an anchor (<code>&lt;a></code>) with an <code>href</code> attribute</li>
<li>Each tab panel may be any valid element but it must have an id which corresponds to the hash in the anchor of the associated tab.</li>
</ul>
<p>The content for each tab panel can be defined in-page or can be loaded via Ajax; both are handled automatically based on the <code>href</code> of the anchor associated with the tab. By default tabs are activated on click, but the events can be changed to hover via the <a href="#option-event"><code>event</code></a> option.</p>
<p>Below is some sample markup:</p>
<pre><code><![CDATA[
<div id="tabs">
<ul>
<li><a href="#fragment-1">One</a></li>
<li><a href="#fragment-2">Two</a></li>
<li><a href="#fragment-3">Three</a></li>
</ul>
<div id="fragment-1">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
</div>
<div id="fragment-2">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
</div>
<div id="fragment-3">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
</div>
</div>
]]></code></pre>
<h3>Keyboard interaction</h3>
<p>When focus is on a tab, the following key commands are available:</p>
<ul>
<li><code>UP</code>/<code>LEFT</code>: Move focus to the previous tab. If on first tab, moves focus to last tab. Activate focused tab after a short delay.</li>
<li><code>DOWN</code>/<code>RIGHT</code>: Move focus to the next tab. If on last tab, moves focus to first tab. Activate focused tab after a short delay.</li>
<li><code>CTRL</code> + <code>UP</code>/<code>LEFT</code>: Move focus to the previous tab. If on first tab, moves focus to last tab. The focused tab must be manually activated.</li>
<li><code>CTRL</code> + <code>DOWN</code>/<code>RIGHT</code>: Move focus to the next tab. If on last tab, moves focus to first tab. The focused tab must be manually activated.</li>
<li><code>HOME</code>: Move focus to the first tab. Activate focused tab after a short delay.</li>
<li><code>END</code>: Move focus to the last tab. Activate focused tab after a short delay.</li>
<li><code>CTRL</code> + <code>HOME</code>: Move focus to the first tab. The focused tab must be manually activated.</li>
<li><code>CTRL</code> + <code>END</code>: Move focus to the last tab. The focused tab must be manually activated.</li>
<li><code>SPACE</code>: Activate panel associated with focused tab.</li>
<li><code>ENTER</code>: Activate or toggle panel associated with focused tab.</li>
<li><code>ALT</code>/<code>OPTION</code> + <code>PAGE UP</code>: Move focus to the previous tab and immediately activate.</li>
<li><code>ALT</code>/<code>OPTION</code> + <code>PAGE DOWN</code>: Move focus to the next tab and immediately activate.</li>
</ul>
<p>When focus is in a panel, the following key commands are available:</p>
<ul>
<li><code>CTRL</code> + <code>UP</code>: Move focus to associated tab.</li>
<li><code>ALT</code>/<code>OPTION</code> + <code>PAGE UP</code>: Move focus to the previous tab and immediately activate.</li>
<li><code>ALT</code>/<code>OPTION</code> + <code>PAGE DOWN</code>: Move focus to the next tab and immediately activate.</li>
</ul>
<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<ul>
<li>
<code>ui-tabs</code>: The outer container of the tabs. This element will additionally have a class of <code>ui-tabs-collapsible</code> when the <a href="#option-collapsible"><code>collapsible</code> option</a> is set.
<ul>
<li>
<code>ui-tabs-nav</code>: The list of tabs.
<ul>
<li><code>ui-tabs-tab</code>: One of the items in the list of tabs.The active item will have the <code>ui-tabs-active</code> class. Any list item whose associated content is loading via an Ajax call will have the <code>ui-tabs-loading</code> class.
<ul>
<li><code>ui-tabs-anchor</code>: The anchors used to switch panels.</li>
</ul>
</li>
</ul>
</li>
<li><code>ui-tabs-panel</code>: The panels associated with the tabs. Only the panel whose corresponding tab is active will be visible.</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="/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.0</added>
<options>
<option name="active" default="0" example-value="1">
<desc>
Which panel is currently open.
</desc>
<type name="Boolean">
<desc>Setting <code>active</code> to <code>false</code> will collapse all panels. This requires the <a href="#option-collapsible"><code>collapsible</code></a> option to be <code>true</code>.</desc>
</type>
<type name="Integer">
<desc>The zero-based index of the panel that is active (open). A negative value selects panels going backward from the last panel.</desc>
</type>
</option>
<option name="classes" type="Object">
<default>{
"ui-tabs": "ui-corner-all",
"ui-tabs-nav": "ui-corner-all",
"ui-tabs-tab": "ui-corner-top",
"ui-tabs-panel": "ui-corner-bottom"
}</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="collapsible" type="Boolean" default="false" example-value="true">
<desc>When set to <code>true</code>, the active panel can be closed.</desc>
</option>
<option name="disabled" default="false" example-value="[ 0, 2 ]">
<desc>Which tabs are disabled.</desc>
<type name="Boolean">
<desc>Enable or disable all tabs.</desc>
</type>
<type name="Array">
<desc>An array containing the zero-based indexes of the tabs that should be disabled, e.g., <code>[ 0, 2 ]</code> would disable the first and third tab.</desc>
</type>
</option>
<option name="event" type="String" default='"click"' example-value='"mouseover"'>
<desc>The type of event that the tabs should react to in order to activate the tab. To activate on hover, use <code>"mouseover"</code>.</desc>
</option>
<option name="heightStyle" type="String" default='"content"' example-value='"fill"'>
<desc>
Controls the height of the tabs widget and each panel. Possible values:
<ul>
<li><code>"auto"</code>: All panels will be set to the height of the tallest panel.</li>
<li><code>"fill"</code>: Expand to the available height based on the tabs' parent height.</li>
<li><code>"content"</code>: Each panel will be only as tall as its content.</li>
</ul>
</desc>
</option>
<xi:include href="../includes/widget-option-hide.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-option-show.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</options>
<events>
<event name="activate">
<desc>
<p>Triggered after a tab has been activated (after animation completes). If the tabs were previously collapsed, <code>ui.oldTab</code> and <code>ui.oldPanel</code> will be empty jQuery objects. If the tabs are collapsing, <code>ui.newTab</code> and <code>ui.newPanel</code> will be empty jQuery objects.</p>
<div class="warning"><strong>Note:</strong> Since the <code>activate</code> event is only fired on tab activation, it is not fired for the initial tab when the tabs widget is created. If you need a hook for widget creation use the <a href="#event-create"><code>create</code></a> event.</div>
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="newTab" type="jQuery">
<desc>The tab that was just activated.</desc>
</property>
<property name="oldTab" type="jQuery">
<desc>The tab that was just deactivated.</desc>
</property>
<property name="newPanel" type="jQuery">
<desc>The panel that was just activated.</desc>
</property>
<property name="oldPanel" type="jQuery">
<desc>The panel that was just deactivated.</desc>
</property>
</argument>
</event>
<event name="beforeActivate">
<desc>Triggered immediately before a tab is activated. Can be canceled to prevent the tab from activating. If the tabs are currently collapsed, <code>ui.oldTab</code> and <code>ui.oldPanel</code> will be empty jQuery objects. If the tabs are collapsing, <code>ui.newTab</code> and <code>ui.newPanel</code> will be empty jQuery objects.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="newTab" type="jQuery">
<desc>The tab that is about to be activated.</desc>
</property>
<property name="oldTab" type="jQuery">
<desc>The tab that is about to be deactivated.</desc>
</property>
<property name="newPanel" type="jQuery">
<desc>The panel that is about to be activated.</desc>
</property>
<property name="oldPanel" type="jQuery">
<desc>The panel that is about to be deactivated.</desc>
</property>
</argument>
</event>
<event name="beforeLoad">
<desc>
<p>Triggered when a remote tab is about to be loaded, after the <a href="#event-beforeActivate"><code>beforeActivate</code></a> event. Can be canceled to prevent the tab panel from loading content; though the panel will still be activated. This event is triggered just before the Ajax request is made, so modifications can be made to <code>ui.jqXHR</code> and <code>ui.ajaxSettings</code>.</p>
<p><em>Note: Although <code>ui.ajaxSettings</code> is provided and can be modified, some of these properties have already been processed by jQuery. For example, <a href="//api.jquery.com/jQuery.ajaxPrefilter/">prefilters</a> have been applied, <code>data</code> has been processed, and <code>type</code> has been determined. The <code>beforeLoad</code> event occurs at the same time, and therefore has the same restrictions, as the <code>beforeSend</code> callback from <a href="//api.jquery.com/jQuery.ajax/"><code>jQuery.ajax()</code></a>.</em></p>
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="tab" type="jQuery">
<desc>The tab that is being loaded.</desc>
</property>
<property name="panel" type="jQuery">
<desc>The panel which will be populated by the Ajax response.</desc>
</property>
<property name="jqXHR" type="jqXHR">
<desc>The <code>jqXHR</code> object that is requesting the content.</desc>
</property>
<property name="ajaxSettings" type="Object">
<desc>The properties that will be used by <a href="//api.jquery.com/jQuery.ajax/"><code>jQuery.ajax</code></a> to request the content.</desc>
</property>
</argument>
</event>
<event name="create">
<desc>Triggered when the tabs are created. If the tabs are collapsed, <code>ui.tab</code> and <code>ui.panel</code> will be empty jQuery objects.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="tab" type="jQuery">
<desc>The active tab.</desc>
</property>
<property name="panel" type="jQuery">
<desc>The active panel.</desc>
</property>
</argument>
</event>
<event name="load">
<desc>Triggered after a remote tab has been loaded.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="tab" type="jQuery">
<desc>The tab that was just loaded.</desc>
</property>
<property name="panel" type="jQuery">
<desc>The panel which was just populated by the Ajax response.</desc>
</property>
</argument>
</event>
</events>
<methods>
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<method name="disable">
<signature>
<desc>Disables all tabs.</desc>
</signature>
<signature example-params="1">
<desc>
Disables a tab. The selected tab cannot be disabled. To disable more than one tab at once, set the <a href="#option-disabled"><code>disabled</code></a> option: <code>$( "#tabs" ).tabs( "option", "disabled", [ 1, 2, 3 ] )</code>.
</desc>
<argument name="index" type="Number">
<desc>The zero-based index of the tab to disable.</desc>
</argument>
</signature>
<signature example-params='"#foo"'>
<desc>
Disables a tab. The selected tab cannot be disabled.
</desc>
<argument name="href" type="String">
<desc>The <code>href</code> of the tab to disable.</desc>
</argument>
</signature>
</method>
<method name="enable">
<signature>
<desc>Enables all tabs.</desc>
</signature>
<signature example-params="1">
<desc>Enables a tab. To enable more than one tab at once reset the disabled property like: <code>$( "#example" ).tabs( "option", "disabled", [] );</code>.</desc>
<argument name="index" type="Number">
<desc>The zero-based index of the tab to enable.</desc>
</argument>
</signature>
<signature example-params='"#foo"'>
<desc>Enables a tab.</desc>
<argument name="href" type="String">
<desc>The <code>href</code> of the tab to enable.</desc>
</argument>
</signature>
</method>
<method name="load">
<signature example-params="1">
<desc>Loads the panel content of a remote tab.</desc>
<argument name="index" type="Number">
<desc>The zero-based index of the tab to load.</desc>
</argument>
</signature>
<signature example-params='"#foo"'>
<desc>Loads the panel content of a remote tab.</desc>
<argument name="href" type="String">
<desc>The <code>href</code> of the tab to load.</desc>
</argument>
</signature>
</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"/>
<method name="refresh">
<desc>Process any tabs that were added or removed directly in the DOM and recompute the height of the tab panels. Results depend on the content and the <a href="#option-heightStyle"><code>heightStyle</code></a> option.</desc>
</method>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<extension-points>
<method name="_getList" return="jQuery">
<desc>Determine which list should be converted to tabs. By default the first descendant list is used.</desc>
<example>
<desc>Use the list with the class <code>my-tabs</code> or fall back to the default implementation.</desc>
<code><![CDATA[
_getList: function() {
var list = this.element.find( ".my-tabs" );
return list.length ? list.eq( 0 ) : this._super();
}
]]></code>
</example>
</method>
</extension-points>
<example>
<desc>A simple jQuery UI Tabs</desc>
<code><![CDATA[
$( "#tabs" ).tabs();
]]></code>
<html><![CDATA[
<div id="tabs">
<ul>
<li><a href="#fragment-1"><span>One</span></a></li>
<li><a href="#fragment-2"><span>Two</span></a></li>
<li><a href="#fragment-3"><span>Three</span></a></li>
</ul>
<div id="fragment-1">
<p>First tab is active by default:</p>
<pre><code>$( "#tabs" ).tabs(); </code></pre>
</div>
<div id="fragment-2">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
</div>
<div id="fragment-3">
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
</div>
</div>
]]></html>
</example>
<category slug="widgets"/>
</entry>