type: widget

release: 1.5

status: complete

documentation: http://docs.jquery.com/UI/Tabs

demo: http://jqueryui.com/demos/tabs

1 - Description:

A tab strip is used to chunk sections of content into multiple panes that can be shown one at a time, much like the sections in a notebook. Depending on the size of the window and length of tab labels, you can generally create a tab view that contains between two and eight tabs. This rule of thumb is followed because tab strips should never wrap to multiple rows or insert horizontal scrollers for the tabs because of the poor visual connection between the tab and the pane below (yes, these have been seen in the past, but it's not a good thing). If there are too many items to fit in a tab strip, consider re-grouping the tab content into fewer tabs or moving to a different navigation widget like a vertical left navigation bar or tree which can accomodate a larger number of items.

Detailed tab behavior descriptions can be found for Apple OS X and Microsoft Windows.

2 - Visual Design:

3 - Functional Specifications/Requirements:

Specificiations

• Indices are zero-based. 
• There are 3 possibilities to set the initially selected tab:
• active option (highest priority)
• url fragment identifier matching a tab href's fragment identifier: href="#fragment-identifier" 
• the ui-tabs-active class attribute is already specified in HTML source: <li class="ui-tabs-active"> (lowest priority)

• It is possible to initialize an empty tab set and add tabs later on. 

• The active tab cannot be collapsed by activating it a second time unless the collapsible option is set to true. 

• The type of tab (in-page vs. ajax) is determined automatically from the href attribute of the contained anchor elements.

Options

• active (mixed, default: null)
• the zero-based index of the tab that is active (open)
• negative value selects tabs going backward from the last tab
• when collapsible: true, active: false closes all tabs
• when null on initialization, the active tab will be set as follows:
• a tab with an href that matches the fragment identifier from the URL
• a tab with the ui-tabs-active class
• if collapsible, set to false
• set to 0 (first tab) 
• collapsible (boolean, default: false)
• there can be only one tab panel open at once; for collapsible:true, all panels can be closed, otherwise exactly one must be open
• event (string, default: "click")
• the name of the event that is used for activating a tab. To activate on hover, use "mouseover"
• disabled (boolean or array, default: false)
• boolean: fully enable or disable the tabs  
• array: array of zero-based tab indices that are disabled
• heightStyle (string, default "content")
• controls the height of the tab panels
• possible values:
• auto: all panels will be set to the height of the tallest panel
• fill: expand to the available height based on the tabs' parent height
• content: each panel will be only as tall as its content 
• hide (mixed, default: null) 
• TODO: Document common APIs on another page and link to them 
• show (mixed, default: null)
• TODO: Document common APIs on another page and link to them 

Methods

• load( index )
• loads the panel content of a remote tab (specified by index)
• index may also be the href value of the tab 
• enable()
• enables all tabs
• enable( index ) 
• enables the tab at the specified index
• index may also be the href value of the tab 
• disable()
• disables all tabs
• disable( index )
• disables the tab at the specified index 
• index may also be the href value of the tab 
• destroy()
• destroys the tabs, reverting all changes applied by the tabs widget

Events

• beforeActivate (event: [depends on event option])
• triggered directly after a tab is activated
• can be cancelled to prevent the tab from activating  
• ui object:
• newTab (object[jQuery])
• oldTab (object[jQuery])
• newPanel (object[jQuery])
• newPanel (object[jQuery]) 
• activate (event: [depends on event option])
• triggered after the tab has been activated and the associated panels have been shown/hidden
• ui object:
• newTab (object[jQuery])
• oldTab (object[jQuery])
• newPanel (object[jQuery])
• newPanel (object[jQuery]) 
• beforeLoad (event: [depends on event option])
• triggered after beforeActivate for a remote tab
• can be cancelled to prevent the tab panel from loading content 
• ui object:
• tab (object[jQuery])
• panel (object[jQuery])
• jqXHR
• ajaxSettings
• load (event: [depends on event option])
• triggered after a remote tab has been loaded
• ui object:
• tab (object[jQuery])
• panel (object[jQuery]) 

Keyboard

• When focus is on a tab:
• UP/LEFT - Move focus to the previous tab. If on first tab, moves focus to last tab. Activate focused tab after a short delay.
• DOWN/RIGHT - Move focus to the next tab. If on last tab, moves focus to first tab. Activate focused tab after a short delay.
• HOME - Move focus to the first tab. Activate focused tab after a short delay.
• END - Move focus to the last tab. Activate focused tab after a short delay.
• SPACE/ENTER - Activate panel associated with focused tab.
• When focus is in a panel:
• CTRL+UP: Move focus to associated header.

Accessibility

• Follows ARIA best practices with the following exceptions:
• Arrow keys do not immediately activate panels. This allows users to quickly navigate tabs without activating them which may be important for remote tabs.
• CTRL+PAGE UP/DOWN is not supported because of interference with browser shortcuts, as mentioned in the best practices.
• Added CTRL+UP to move to the tab associated with the current panel to enable similar functionality. 
• Added HOME and END support to match accordion implementation.
• TODO
• aria-busy on remote tabs during load
• aria-live="polite" on panels that load remote content 

4 - Markup & Style:

(only used prior to implementation)

5 - Latest version of plugin:

http://view.jqueryui.com/master/demos/tabs/default.html

6 - Open issues being discussed