This translation is only % complete!
We need your help to make Semantic available to people who speak your language.
Our translation tools are easy to use and allow you to translate text without having to leave the site.
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
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()
;
Retreiving Remote Tab Content
Using auto: true will load the tab's path from your server with additional headers to specify an in-page request. Additional requests will automatically be loaded from cache without a server request.
$('.dynamic.example .menu .item')
.tab({
context : '.dynamic.example',
auto : true,
path : '/'
})
;
AJAX Tab One
Multiple Tabs on Same Page
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.
1A
1B
1C
2A
2B
2C
3A
3B
3C
4A
4B
4C
5A
5B
5C
6A
6B
6C
$('#context1 .menu .item')
.tab({
context: $('#context1')
})
;
$('#context2 .menu .item')
.tab({
context: $('#context2')
})
;
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
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
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 apprpopriate 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 set(path) | 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 |
| 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. |
| alwaysRefresh | false | Tab should reload content every time it is opened |
| 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 |
| mayDepth | 25 | Maximum amount of nested tabs allowed (avoids recursion) |
Callbacks
Callbacks specify a function to occur after a specific behavior.
| Parameters | Context | Description | |
|---|---|---|---|
| onTabInit | tabPath, parameterArray, historyEvent | Tab | Callback only the first time a tab is loaded |
| onTabLoad | tabPath, parameterArray, historyEvent | Tab | Callback every time a tab is loaded |
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 |
| 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'
}
|
|