Description
The tab bar widget allows users to switch between individual panels of content. The widget can build panels either from content that already exists on the page, or by loading it from a remote source. The browser URL can additionally be updated to reflect the permalink of the individual tab being selected.
Usage
The tab bar itself should be constructed manually in the markup, with the tabs linking to a static page. This enables the page to be used even when javascript is enabled. This is the basic markup for a tab bar:
<!-- The tab bar --> <div class='ipsTabs ipsClearfix' id='elTabBar' data-ipsTabBar data-ipsTabBar-contentArea='#elTabContent'> <a href='#elTabBar' data-action='expandTabs'><i class='icon-caret-down'></i></a> <ul role='tablist'> <li role='presentation'> <a href='...' role='tab' id='elTabOne' class='ipsTabs_item' aria-selected="true"> Tab One </a> </li> <li role='presentation'> <a href='...' id='elTabTwo' role='tab' class='ipsTabs_item'> Tab Two </a> </li> </ul> </div> <!-- The tab panel wrapper --> <section id='elTabContent'></section>
The key details here are:
- The widget key attributes belong on the tab bar wrapper element.
- The first child of the tab bar should be an element with the attribute data-action='expandTabs'. This is used when the tab bar is displayed on a small device. For accessibility, it should be an anchor link to the tab bar element.
- Each tab links to a static page - this is the same URL that is called to fetch content remotely, too. If your tab panels (see next section) are static content that already exists on the page, you can use an anchor that points to that element instead.
- A panel wrapper is present, which will receive the panels when the tab widget creates them.
- This example is also marked up with ARIA properties for accessibility, such as role='tab' and aria-selected='true'.
If content exists inside the panel wrapper element at the time the tab widget is initialized, the widget will take this content, create a panel from it, and treat it as the content for the default selected tab. This mechanism means developers can include the default content into the page very easily, without it needing to be fetched with another AJAX request.
Panels can be created manually, rather than having them load via AJAX. To do so, a panel element should exist inside the panel wrapper element and have the correct ID. The ID takes this format:
<panelPrefix>_<barID>_<tabID>_panel
Where the values are:
- panelPrefix is the prefix set in the options (see below); ipsTabs by default
- barID is the ID set on the tab bar element
- tabID is the ID set on the individual tab element that this panel relates to
Options
contentArea
(Selector; required)
A CSS selector which will locate the panel container element into which panels will be created. For example, #elTabContent.
updateURL
(Boolean; optional; default true)
Determines whether the browser address bar will be updated with the URL to individual tabs when the user selects them. This allows individual tabs to be navigated to and appear in the browser's history.
itemSelector
(Selector; optional; default '.ipsTab_item')
A CSS selector which will locate the tab elements within the tab bar.
activeClass
(String; optional; default 'ipsTabs_activeItem')
A classname which will be applied to the currently-active tab element.
loadingClass
(String; optional; default 'ipsLoading ipsTabs_loadingContent')
A classname which will be applied to the panel container element when new tab content is being loaded.
panelClass
(String; optional; default 'ipsTabs_panel')
A classname which will be applied to individual panels as they are created.
panelPrefix
(String; optional; default 'ipsTabs')
A prefix which will be used when generating a panel ID. This helps to prevent potential naming conflicts with other elements. The default value should be fine in most situations.
defaultTab
(Selector; optional)
If provided, this option is used to set the default tab when the tab bar first loads. If not provided, the first tab with the class specified by activeClass is looked for; finally, if all else fails, the first tab in the bar is selected.
Additionally, it is worth noting that if you would like for the tab bar to stretch across the entire area of the container it is contained within, you can add the CSS class .ipsTabs_stretch to the tab bar element.
Events emitted by ips.ui.tabbar
tabChanged
Triggered when the selected tab changes. This event is triggered as soon as the user clicks a tab.
Event data:
-
barID
ID of the tab bar wrapper -
tabID
ID of the selected tab -
tab
Reference to the newly-selected tab element -
panel
Reference to the panel element for this tab
tabShown
Triggered when the selected tab is shown. This event is triggered after the fade-in animation has finished, unlike the tabChanged event above.
Event data:
-
barID
ID of the tab bar wrapper -
tabID
ID of the selected tab -
tab
Reference to the newly-selected tab element -
panel
Reference to the panel element for this tab
Report Guide