--- layout : 'default' css : '' element : 'tab' elementType : 'module' title : 'Tab' description : 'A tab is a section of content tied to a navigation menu' type : 'UI Module' themes : ['Default'] --- <%- @partial('header', { tabs: { usage: 'Usage', examples: 'Examples', settings: 'Settings' } }) %>

Initializing Tabs

Tabs are usually used in concert with an element that activates the tab. Tabs are initialized on the activating item instead of the tab.

If there are no menus that activate tab elements on the page, tabs can be initialized globally by using $.tab() and activated programmatically using $.tab('change tab', path);

Tabs are connected to their activators with a metadata attribute data-tab. This should be added to both the activating element and the tab itself.

Default tabs

After any tab is opened it will look for a default tab to open inside of the current tab. This is the first tab that begins with the same stem url as the parent tab. For example a tab with the path data-tab="home" might open a tab automatically data-tab="/home/inbox".

This will happen recursively for every tab open, allowing as many levels of tabs as you like.

Managing State

...with Hash Tags

Hash tags use in page links and onhashstatechange to create history events for each tab. This is sometimes easier to use than the more advanced push state, because it does not require you to route those URLs on your server. All in page links will route to the same url.

$('.ui.menu .item') .tab({ history: true, historyType: 'state' }) ;

...with HTML5 State

Tabs can can use html5 push state to manage page state without using #/foo links. When a user refreshes a page using push state the server will be queried for the new url. This means you must set up appropriate routes in your backend to match each link.

Tabs use Asual's Address library to provide cross-browser push state support. This makes sure in browser that don't support push state, hashchange is used with in page anchors to provide history functionality.

$('.ui.menu .item') .tab({ history: true, historyType: 'state' path: '/modules/tab.html' }) ;

Setting Paths

Make sure when you use history to specify the path. This is required for determining the stem url from the part of the url maintaining in page history. The path is the base URL without any internal state. This cannot be set automatically to window.location because refreshing the page will change future page refreshes the URL may include an internal link.

Using the incorrect path will cause the module to work incorrectly, producing unexpected results.

AJAX Content

...with automatic routing

Specifying the setting auto: true, will automatically retrieve content at a remote url matching the url set in the browser.

So for example the tab inbox will retrieve content from the URL base-url/inbox/

The URL will receive an addition HTTP Header 'X-Remote': true. You can use this on your server's back-end to determine whether a request is an AJAX request from a tab, or a full page request.

Queries with 'X-Remote': true should refresh only the tabbed content, while queries without are normal resources and should refresh the entire page contents

This uses a similar technique to pJax or Rail's turbolinks.

There are a variety of settings for configuring dynamic content behavior. Visit the tab settings section for more information
$('.dynamic.example .menu .item') .tab({ context : '.dynamic.example', auto : true, path : '/modules/tab.html' }) ;

...with an API Behavior

Tabs provide an optional coupling with API which allow you to specify a templated API endpoint that a tab can query

Tabs will automatically pass the url variable {$tab} which can be replaced for RESTful API links.

Behavior

All the following behaviors can be called using the syntax $('.foo').tab('behavior name', argumentOne, argumentTwo)
attach events(selector, event) Attaches tab action to given selector. Default event if none specified is toggle
show Shows tab
hide Hides tab
toggle Toggles visibility of tab
is open Returns whether tab is open
is closed Returns whether tab is closed

Multi-level Tabs with Defaults

This example shows how default tabs are opened recursively for multiple tiers of tabs

Each of these examples is initialized with a context to prevent contamination with other tab examples on this page. This is not necessary unless using multiple tab systems on a single page.
$('.first.example .menu .item') .tab({ context: '.first.example' }) ;
First Second Third
1A 1B 1C
1A
1B
1C
2A 2B 2C
2A
2B
2C
3A 3B 3C
3A
3B
3C

Example with hash page history

$('.history.example .menu .item') .tab({ context : '.history.example', history : true }) ;
First Second Third
1A 1B 1C
1A
1B
1C
2A 2B 2C
2A
2B
2C
3A 3B 3C
3A
3B
3C

Retreiving Dynamic Tab Content

$('.dynamic.example .menu .item') .tab({ context : '.dynamic.example', auto : true, path : '/modules/tab.html' }) ;
First Second Third
1A 1B 1C
2A 2B 2C
3A 3B 3C

Transition Settings
Form settings modify the transition behavior

Setting Default Description
overlay false Whether tab should overlay page instead of pushing page to the side
useCSS true Whether to use css animations or fallback javascript animations
duration 300 Duration of side bar animation

DOM Settings
DOM settings specify how this module should interface with the DOM

Setting Default Description
namespace tab Event namespace. Makes sure module teardown does not effect other events attached to an element.
className
className: { active : 'active', pushed : 'pushed', top : 'top', left : 'left', right : 'right', bottom : 'bottom' }
Class names used to attach style to state

Debug Settings
Debug settings controls debug output to the console

Setting Default Description
name Tab Name used in debug logs
debug True Provides standard debug output to console
performance True Provides standard debug output to console
verbose True Provides ancillary debug output to console
errors
error : { method : 'The method you called is not defined.', notFound : 'There were no elements that matched the specified selector' }