Type
Tab
A basic tab
States
Active
A tab can be activated, and visible on the page
Loading
A tab can display a loading indicator
Basic Examples
Basic Tabs
Tabs are connecting using paths specified in the data-tab attribute. Tab is then initialized in Javascript on the activating elements.
First
Second
Third
$('.menu .item')
.tab()
;
Multiple Tab Groups
There are a several of ways to include independent tab groups on the same page, even with history. One of the easiest ways is provide a specific parent context for each tab group.
$('#context1 .menu .item')
.tab({
context: $('#context1')
})
;
$('#context2 .menu .item')
.tab({
// special keyword works same as above
context: 'parent'
})
;
1A
1B
1C
2A
2B
2C
3A
3B
3C
4
5
6
1A
1B
1C
2A
2B
2C
3A
3B
3C
4
5
6
Default Paths
When you specify a path like first/ after opening the tab it will look for the any child paths and open the first. In this example even if the path is first/, the tab corresponding with first/a will automatically also be open because it is the default child tab. This will work recursively for as many additional child tab groups as you include.
$('.paths.example .menu .item')
.tab({
context: '.paths.example'
})
;
1A
1B
1C
2A
2B
2C
3A
3B
3C
Remote Examples
Retreiving Remote Content
Using auto: true will load the tab's path from your server with additional headers to specify an in-page request. When cache: true is set, re-opening a tab will be loaded from cache without a server request.
$('.dynamic.example .menu .item')
.tab({
cache: false,
// faking API request
apiSettings: {
loadingDuration : 300,
mockResponse : function(settings) {
var response = {
first : 'AJAX Tab One',
second : 'AJAX Tab Two',
third : 'AJAX Tab Three'
};
return response[settings.urlData.tab];
}
},
context : 'parent',
auto : true,
path : '/'
})
;
AJAX Tab One
Evaluating Scripts in HTML
By default, script tags included in HTML will only be evaluated on first load. To change this behavior you can adjust the evaluateScripts setting.
$('.eval.example .menu .item')
.tab({
evaluateScripts : 'once',
context : 'parent',
auto : true,
path : '/'
})
;
AJAX Tab One
History Examples
Using Hash History
For static sites, or sites that only require simple history, in-page links can be used to trigger different local tab states
$('.history.example .menu .item')
.tab({
context : '.history.example',
history : true
})
;
1A
1B
1C
2A
2B
2C
3A
3B
3C
Using HTML5 State
For sites that are able to replicate change on the server, tab can automatically map changes in tab navigation to html5 state.
$('.ui.menu .item')
.tab({
history : true,
historyType : 'state',
// base url for all other path changes
path : '/my/base/url'
})
;
Initializing Tabs
...with Menus
Tabs are usually used in concert with an element that activates the tab. Tabs are initialized on the activating item instead of the tab.
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.
$('.tabular.menu .item').tab();
...without Menus
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);
$('.ui.button')
.on('click', function() {
// programmatically activating tab
$.tab('change tab', 'tab-name');
})
;
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: 'hash'
})
;
...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.
$('.ui.menu .item')
.tab({
history: true,
historyType: 'state',
path: '/modules/tab.html'
})
;
Setting Paths
Using historyType: state requires specifying a base URL without any internal state. This cannot be set automatically to window.location because all tabs with html5 state will appear as normal page urls, and route accordingly.
HTML5 state will only work with dynamic site back-ends because it requires each tab path to correctly route on the server to the appropriate content.
$('.ui.menu .item')
.tab({
history: true,
historyType: 'state'
path: '/modules/tab.html'
})
;
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.
$('.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.
To learn more about API behaviors built into semantic check out the API docs
View API DocsBehavior
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 |
| change tab(path) | Changes tab to path |
| set state(path) | Sets current path to state |
| get path | Returns current path |
| is tab | Returns whether tab exists |
| cache read(path) | Returns cached HTML for path |
| cache add(path, html) | Sets cached HTML for path |
| cache remove(path) | Removes cached HTML for path |
Tab Settings
Form settings modify the tab behavior
| Setting | Default | Description |
|---|---|---|
| auto | false | Whether tab should load remote content as same url as history |
| deactivate | 'siblings' | When set to siblings will only deactivate elements that are DOM siblings with the activated element. When set to all the component will deactivate all other elements initialized at the same time. |
| history | false | Whether to record history events for tab changes |
| ignoreFirstLoad | false | Do not load content remotely on first tab load. Useful when open tab is rendered on server. |
| evaluateScripts | once | Whether inline scripts in tab HTML should be parsed on tab load. Defaults to once, parsing only on first load. Can also be set to true or false to always parse or never parse inline scripts. |
| alwaysRefresh | false | Tab should reload content every time it is opened |
| deactivate 2.2 |
siblings | Can be set to either siblings or all. Siblings will only de-activate tab activators that are siblings of the clicked element when a tab is selected. All will deactivate all other tab activators initialized at the same time. |
| cacheType 2.2 |
response | Can be set to either response, DOM or html. Using DOM will cache the a clone of the DOM tree, preserving all events as they existed on render. response will cache the original response on load, this way callbacks always receive the same content. Using html will cache the resulting html after all callbacks, making sure any changes to content are preserved. |
| cache | true | Tab should cache content after loading locally to avoid server trip on second load |
| apiSettings | false | Settings object for $.api call |
| historyType | hash | Can be set to hash or state. Hash will use an in-page link to create history events. State will use DOM History and load pages from server on refresh. |
| path | false | When using historyType state you must specify the base URL for all internal links. |
| context | false | Tabs are limited to those found inside this context |
| childrenOnly | false | If enabled limits tabs to children of passed context |
| maxDepth | 25 | Maximum amount of nested tabs allowed (avoids recursion) |
Callbacks
Callbacks specify a function to occur after a specific behavior.
| Parameters | Context | Description | |
|---|---|---|---|
| onFirstLoad | tabPath, parameterArray, historyEvent | Tab | Callback only the first time a tab is loaded |
| onLoad | tabPath, parameterArray, historyEvent | Tab | Callback every time a tab is loaded |
| onRequest | tabPath | Tab | Called when a tab begins loading remote content |
| onVisible | tabPath | Tab | Called after a tab becomes visible |
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. |
| templates |
templates : {
// returns page title
determineTitle: function(tabArray) {}
}
|
Functions used to return content |
| selector |
selector : {
tabs : '.ui.tab',
parent : '.ui:not(.menu)'
}
|
Selectors used by module |
| metadata |
metadata : {
tab : 'tab',
loaded : 'loaded',
promise: 'promise'
}
|
DOM metadata used by module |
| className |
className : {
loading : 'loading',
active : 'active'
}
|
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 |
| silent | False | Silences all console output including error messages, regardless of other debug settings. |
| debug | False | Provides standard debug output to console |
| performance | True | Provides standard debug output to console |
| verbose | True | Provides ancillary debug output to console |
| errors |
error: {
api : 'You attempted to load content without API module',
method : 'The method you called is not defined',
missingTab : 'Activated tab cannot be found for this context.',
noContent : 'The tab you specified is missing a content url.',
path : 'History enabled, but no path was specified',
recursion : 'Max recursive depth reached',
state : 'The state library has not been initialized'
}
|
|