# Tabbed Interface

Questions or comments?

## Purpose

Dynamically stacks multiple sections of content, transforming them into a tabbed interface. Implements the WAI-ARIA tab panel design pattern for large screens and the WAI-ARIA accordion design pattern for small screens.

## Working example

- English example
- French example
- English carousel example
- French carousel example

## How to implement

### Tabbed interface

1. Add a `div` element to the page with the class `wb-tabs`.
2. Add a `div` element to the previous `div` element with the class `tabpanels`.
3. For each tab panel, add a `details` element with a unique `id`. Add `open="open"` for the tab panel that should be open by default.

       <div class="wb-tabs">
       	<div class="tabpanels">
       		<details id="details-panel1">
       			...
       		</details>
       		<details id="details-panel2" open="open">
       			...
       		</details>

4. Add a `summary` element with the label of the tab to each `details` element.

       <details id="details-panel1">
       		<summary>Example 1</summary>
       		...
       	</details>
       	<details id="details-panel2" open="open">
       		<summary>Example 2</summary>
       		...
       	</details>

5. Add the tab panel content after each `summary` element.

#### Code

    <div class="wb-tabs">
    	<div class="tabpanels">
    		<details id="details-panel1">
    			<summary>Example 1</summary>
    			<p>
    				...
    			</p>
    		</details>
    		<details id="details-panel2" open="open">
    			<summary>Example 2</summary>
    			<p>
    				...
    			</p>
    		</details>
    		...
    	</div>
    </div>

### Carousel

1. Add a `div` element to the page with the class `wb-tabs` and either the styling class `carousel-s1` or `carousel-s2`.
2. Add a `div` element to the previous `div` element with the class `tabpanels`.
3. For each tab panel, add a `div` element with a unique id, `role="tabpanel"` and `class="out"`. For the tab panel that should be opened by default, replace the `out` class with `in`.
4. Specify the tab panel transition type by adding one of the following classes to the `div` element for each of the tab panels:
   - `fade`: Fading transition
   - `slide`: Horizontal sliding transition
   - `slidevert`: Vertical sliding transition

       <div class="wb-tabs carousel-s1">
       	<div class="tabpanels">
       		<div role="tabpanel" id="panel1" class="in fade">
       		</div>
       		<div role="tabpanel" id="panel2" class="out fade">
       		</div>
       	</div>
       </div>

5. Add a `figure` element to each tab panel.
6. Add content to each `figure` element:
   - Image: Add an image to the `figure` element followed by a `figcaption` element with the caption for the tab panel.

         <div role="tabpanel" id="panel1" class="in fade">
         	<figure>
         		<img src="img/protect-environment.jpg" alt="Panel 1" />
         		<figcaption>
         			<p>
         				Take Note: <a href="http://www.tc.gc.ca/eng/civilaviation/opssvs/general-personnel-changes-1814.htm">Renewal of the Aviation Document Booklet</a>&#160;<br />
         				Learn more about <a href="http://www.tc.gc.ca/eng/air-menu.htm">air transportation</a> in Canada.
         			</p>
         		</figcaption>
         	</figure>
         </div>

   - Video: Add a multimedia player to the `figure` element according to the multimedia player documentation.

         <div role="tabpanel" id="panel1" class="in fade">
         	<figure class="wb-mltmd">
         		<video poster="../multimedia/demo/video1-en.jpg" title="Looking for a Job">
         			<source type="video/webm" src="http://video2.servicecanada.gc.ca/video/boew-wet/te-lj-eng.webm" />
         			<source type="video/mp4" src="http://video2.servicecanada.gc.ca/video/boew-wet/te-lj-eng.mp4" />
         			<track src="../multimedia/cpts-lg-en.html" kind="captions" data-type="text/html" srclang="en" label="English" />
         		</video>
         		<figcaption>
         			<p>Looking for a Job (<a href="../multimedia/cpts-lg-en.html">Transcript</a>)</p>
         		</figcaption>
         	</figure>
         </div>

   - Other content: Add content to the `figure` element followed by a `figcaption` element with the caption for the tab panel.

         <div role="tabpanel" id="panel1" class="in fade">
         	<figure>
         		<table>
         			...
         		</table>
         		<figcaption>
         			<p>Tab panel caption</p>
         		</figcaption>
         	</figure>
         </div>

7. Add a `ul` element with `role="tablist"` at the start of the `div` element with the `wb-tabs` class.
8. For each tab panel, add an `li` element to the previous `ul` element. Add `class="active"` for the tab panel that should be open by default.
9. Add an `a` element to each `li` element
10. Add to each `li` element an `a` element with the label of the tab and that links to the associated tab panel.

        <ul role="tablist">
        	<li class="active"><a href="#panel27">Tab 1</a></li>
        	<li><a href="#panel28">Tab 2</a></li>
        		...
        </ul>

11. Optional: Override the default settings using the configuration options.
12. Optional: Add an external link that affects which tab is visible. The href attribute includes the id of the panel to make visible. (v4.0.8+)

        <p><a href="#panel3" class="wb-tabs-ext">Show the third panel</a></p>

#### Code

    <div class="wb-tabs carousel-s1">
    	<ul role="tablist">
    		<li class="active"><a href="#panel1">Tab 1</a></li>
    		<li><a href="#panel2">Tab 2</a></li>
    		...
    	</ul>
    	<div class="tabpanels">
    		<div role="tabpanel" id="panel1" class="in fade">
    			<figure>
    				<img src="img/protect-environment.jpg" alt="Panel 1" />
    				<figcaption>
    					<p>
    						...
    					</p>
    				</figcaption>
    			</figure>
    		</div>
    		<div role="tabpanel" id="panel2" class="out fade">
    			<figure>
    				<img src="img/banff.jpg" alt="Panel 2" />
    				<figcaption>
    					<p>
    						...
    					</p>
    				</figcaption>
    			</figure>
    		</div>
    		...
    	</div>
    </div>

## Configuration options - Tabbed interface and carousel

Option | Description | How to configure | Values
--- | --- | --- | ---
Update the URL hash (`data-wb-tabs`) (v4.0.9+) | Configure the tab interface or carousel to update the URL hash every time the tab panel changes through the `updateHash` property of the `data-wb-tabs` attribute. | Add the `data-wb-tabs` attribute to the element with `class="wb-tabs"` and include the `updateHash` property with a true or false value.
    data-wb-tabs='{"updateHash": true}'
| `false` (default): URL hash is not updated every time the tab panel changes `true` (default): URL hash is updated every time the tab panel changes
Update the URL hash (`update-hash`) (v4.0.9+) | Configure the tab interface or carousel to update the URL hash every time the tab panel changes through the `update-hash` class. | Add `update-hash` after the `wb-tabs` class.
    class="wb-tabs update-hash"
| None (default): URL hash is not updated every time the tab panel changes `update-hash` URL hash is updated every time the tab panel changes
Ignore session storage (`data-wb-tabs`) (v4.0.12+) | Configure the tab interface to remain on the first or default selected tab on all page loads through the `ignoreSession` property of the `data-wb-tabs` attribute. | Add the `data-wb-tabs` attribute to the element with `class="wb-tabs"` and include the `ignoreSession` property with a true or false value.
    data-wb-tabs='{"ignoreSession": true}'
| `false` (default): Last selected tab is displayed every time the page is loaded `true` (default): First or default selected tab is displayed every time the page is loaded
Ignore session storage (`ignore-session`) (v4.0.12+) | Configure the tab interface to remain on the first or default selected tab on all page loads through the `ignore-session` class. | Add `ignore-session` after the `wb-tabs` class.
    class="wb-tabs ignore-session"
| None (default): Last selected tab is displayed every time the page is loaded `ignore-session` First or default selected tab is displayed every time the page is loaded
Print only the active (visible) panel (`print-active`) (v4.0.15+) | Configure the tab interface to print only the active (visible) panel through the `print-active` class. | Add `print-active` after the `wb-tabs` class.
    class="wb-tabs print-active"
| None (default): All panels are printed `print-active` Only the active panel is printed

## Configuration options - Carousel only

Option | Description | How to configure | Values
--- | --- | --- | ---
Carousel style | Configures the carousel style. | Add the value after the `wb-tabs` class (e.g., `class="wb-tabs carousel-s1"`) | `carousel-s1`: Square grey controls located at the top of the carousel. `carousel-s2`: Rounded white controls located at the bottom of the carousel.
Change rotation speed (`data-wb-tabs`) | Configure the tab rotation speed through the `interval` property of the `data-wb-tabs` attribute. | Add the `data-wb-tabs` attribute to the element with `class="wb-tabs"` and include the `interval` property with the number of seconds between tab rotations.
    data-wb-tabs='{"interval": 3}'
| `6` (default): Six seconds between tab rotations Integer Number of seconds between tab rotations
Change rotation speed (`slow`, `fast`) | Configure the tab rotation speed through either the `slow` or `fast` classes. | Add either `slow` or `fast` after the `wb-tabs` class.
    class="wb-tabs slow"
| None (default): Six seconds between tab rotations `slow` Nine seconds between tab rotations `fast` Three seconds between tab rotations
Tab panel transitions | Configure the tab panel transition type through the `fade`, `slide` or `slidevert` classes. | Add `fade`, `slide` or `slidevert` after the `in` or `out` class on each tab panel.
    <div role="tabpanel" id="panel21" class="in fade">
| `fade`: Fading transition `slide` Horizontal sliding transition `slidevert` Vertical sliding transition
Exclude play (`data-wb-tabs`) (v4.0.5+) | Exclude the play button from the carousel controls through the `excludePlay` property of the `data-wb-tabs` attribute. | Add the `data-wb-tabs` attribute to the element with `class="wb-tabs"` and include the `excludePlay` property with `true` for the value.
    data-wb-tabs='{"excludePlay": true}'
| `false` (default): Play button is included in the carousel controls. `true`: Play button is excluded from the carousel controls.
Exclude play (`exclude-play`) (v4.0.5+) | Exclude the play button from the carousel controls through the `exclude-play` class. | Add `exclude-play` after the `wb-tabs` class.
    class="wb-tabs exclude-play"
| None (default): Play button is included in the carousel controls. `playing` Play button is excluded from the carousel controls.
Play on page load (`data-wb-tabs`) (v4.0.5+) | Play the carousel on page load through the `playing` property of the `data-wb-tabs` attribute. Warning: Playing on page load can be distracting and cause usability issues for some users. Note: Playing will be disabled if the play button is excluded from the carousel controls. | Add the `data-wb-tabs` attribute to the element with `class="wb-tabs"` and include the `playing` property with `true` for the value.
    data-wb-tabs='{"playing": true}'
| `false` (default): Carousel does not play on page load. `true`: Carousel plays on page load.
Play on page load (`playing`) | Play the carousel on page load through the `playing` class. Warning: Playing on page load can be distracting and cause usability issues for some users. Note: Playing will be disabled if the play button is excluded from the carousel controls. | Add `playing` after the `wb-tabs` class.
    class="wb-tabs playing"
| None (default): Carousel does not play on page load. `playing` Carousel plays on page load.

## Events

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-tabs` | Triggered manually (e.g., `$( ".wb-tabs" ).trigger( "wb-init.wb-tabs" );`). | Used to manually initialize the Tabbed interface plugin. Note: The Tabbed interface plugin will be initialized automatically unless the required markup is added after the page has already loaded.
`wb-ready.wb-tabs` (v4.0.5+) | Triggered automatically after a tabbed interface or carousel initializes. | Used to identify which tabbed interface or carousel was initialized (target of the event)
    $( document ).on( "wb-ready.wb-tabs", ".wb-tabs", function( event ) {
    });
    $( ".wb-tabs" ).on( "wb-ready.wb-tabs", function( event ) {
    });
`wb-updated.wb-tabs` (v4.0.5+) | Triggered automatically after a tabbed interface/carousel was updated (visible tab panel changed). | Used to identify which tabbed inteface/carousel was updated (target of the event) and to pass along the newly visible panel (as a jQuery object).
    $( document ).on( "wb-updated.wb-tabs", ".wb-tabs", function( event, $newPanel ) {
    });
    $( ".wb-tabs" ).on( "wb-updated.wb-tabs", function( event, $newPanel ) {
    });
`wb-shift.wb-tabs` | Triggered manually or automatically to change which tab panel is visible. | Changes which tab panel is visible. The value of `shiftto` is the number of tab panels to move forwards (positive number) or backwards (negative number).
    $elm.trigger({
    	type: "wb-shift.wb-tabs",
    	shiftto: 1
    });
`wb-select.wb-tabs` (v4.0.8+) | Triggered manually or automatically to change which tab panel is visible. | Changes which tab panel is visible. The value of `id` is the id attribute of the tab panel to make visible.
    $elm.trigger({
    	type: "wb-select.wb-tabs",
    	id: "panel3"
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Tabbed interface plugin source code on GitHub

Date modified:
  2018-04-18