# Basculer

Questions ou commentaires?

Needs translation

## Purpose

Allows an element to toggle elements between on and off states. The element that is toggled records its current state using a ".on" or ".off" CSS class. The accordion option implements the WAI-ARIA accordion design pattern.

## Use when

- Clicking an element should control the state of itself or other elements on the page (e.g. a button to open/close all `<details>` elements).
- Elements should change state when the page is printed (`<details>` elements should be automatically opened for print).
- Accordion widget behaviour is needed.

## Do not use when

- The element being toggled already supports the behaviour natively (e.g. `<details>` elements).

## Working example

English example

French example

## How to implement

### Toggle self

This is the most basic use of the plugin. It allows an element to toggle itself on and off when clicked.

1. Add the `wb-toggle` CSS class to an element.

    <button type="button" class="wb-toggle">Toggle</button>

### Toggle other elements

A toggle element can be setup to control the on/off toggle state of other elements. Any elements that match the CSS selector specified by the data-toggle attribute will have their on/off state changed when the toggle element is clicked.

1. Add the `wb-toggle` CSS class to the toggle element.
2. Using the `data-toggle` attribute, specify the CSS selector of the elements that will have their states toggled.

    <button type="button" class="wb-toggle" data-toggle="{'selector': '.otherElements'}">Toggle</button>

### Toggle configuration

This example expands on Toggle other elements by using the plugin's configuration options.

1. Add the `wb-toggle` CSS class to the toggle element.
2. Using the `data-toggle` data attribute, specify
   - the CSS selector of the elements that will have their states toggled,
   - the CSS selector of the parent these elements must exist in,
   - that toggle is "on" only,
   - that elements should be toggled "on" when the page is printed, and
   - that the toggle state should be saved between page loads using sessionStorage.

    <button type="button" class="wb-toggle" data-toggle="{
    		'selector': '.otherElements',
    		'parent': '#parentElement',
    		'type': 'on',
    		'print': 'on',
    		'persist': 'session'}">Toggle</button>

### Grouped Toggle

This option causes a group of elements to only allow one of the elements to be active ("on") at a time, much like a tabbed interface.

1. Add the `wb-toggle` CSS class to the toggle elements.
2. Using the `data-toggle` attribute, specify the element(s) the toggle element will control, and the group CSS selector.

The following shows a completed example for button elements that toggle open details elements:

    <button type="button" class="wb-toggle" data-toggle='{"selector": "#toggle1", "group": ".grouped", "type": "on"}'>Example 1</button>
    	<button type="button" class="wb-toggle" data-toggle='{"selector": "#toggle2", "group": ".grouped", "type": "on"}'>Example 2</button>

    	<details id="toggle1" class="grouped">
    		<!-- content -->
    	</details>
    	<details id="toggle2" class="grouped">
    		<!-- content -->
    	</details>

### Accordion

The group toggle feature of the plugin can also be used to create an accordion.

1. Wrap all sections of the accordion in parent element with a unique CSS class or ID. `<div class="accordion">`
2. For each accordion section:
   - Add the `wb-toggle` class and `data-toggle` attribute to the element the user will click to open/close the section.
   - Add the `tgl-tab` class to the element that shows the section's heading.
   - Wrap the content in a `<div class="tgl-panel">` element.

If details elements are used for the accordion sections, the HTML should look like the following once finished:

    <div class="accordion">

    		<!-- Accordion section 1 -->
    		<details class="acc-group">
    			<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Section 1's heading</summary>
    			<div class="tgl-panel">
    				<!-- Section 1's content -->
    			</div>
    		</details>

    		<!-- Accordion section 2 -->
    		<details class="acc-group">
    			<summary class="wb-toggle tgl-tab" data-toggle='{"parent": ".accordion", "group": ".acc-group"}'>Section 2's heading</summary>
    			<div class="tgl-panel">
    				<!-- Section 2's content -->
    			</div>
    		</details>

    	</div>

## Configuration options

All configuration options of the plugin are controlled by the `data-toggle` attribute:

Option | Description | How to configure | Values
--- | --- | --- | ---
`selector` | CSS selector that specifies the elements the toggle element controls. If no CSS selector is supplied, the toggle element controls itself. | Specify the CSS selector. All elements to be toggled should match this selector.
    <span class="wb-toggle" data-toggle='{"selector": ".cssSelector"}">
| None (default): Toggle element toggles itself. String: CSS selector. All elements that match this selector will be toggled when the toggle element is clicked.
`parent` | CSS selector that causes the toggle element to only control elements within a given parent element. | Specify the CSS selector. When a toggle element is clicked, it will only toggle elements that are children of this selector.
    <span class="wb-toggle" data-toggle='{"parent": ".parentCssSelector"}'>
| None (default): No parent element restriction. String: CSS selector. When a toggle element is clicked, it will only toggle the elements that are children of this selector.
`group` | CSS selector that groups multiple toggle elements together and only allows one of the elements to be open at a time. | Specify the CSS group selector. All elements to be toggled should match this selector.
    <span class="wb-toggle" data-toggle='{"group": ".groupCssSelector"}">
| None (default): No grouping behaviour. String: CSS selector. When a toggle element is clicked, all other elements that match this selector will be closed.
`persist` | Causes a toggle element to remember its current state and re-apply it when the page reloads. | Supports persistence. Only "session" and "local" are supported:
    <span class="wb-toggle" data-toggle='{"persist": "session"}'>
| None (default): Element will not change state for printing. "session": Toggle state will persist until the user closes their browser window or tab. "local": Toggle state will persist even after the browser window or tab is closed.
`print` | Causes a toggle element to turn the elements it controls on or off when the page is printed. | Specify the print behaviour. Only "on" or "off" are supported:
    <span class="wb-toggle" data-toggle='{"print": "on"}'>
| None (default): Element will not change state for printing. "on": Elements will be set to "on" toggle state for printing. "off": Elements will be set to "off" toggle state for printing.
`type` | Causes a toggle element to only turn the elements it controls on or off. | Specify the type. Only "on" or "off" are supported:
    <span class="wb-toggle" data-toggle='{"type": "on"}'>
| None (default): Toggle element will alternate back and forth between states (on and off) "on": Toggle element will only turn elements it controls on. "off": Toggle element will only turn elements it controls off.
`state` (v4.0.11+) | Sets the initial state of a toggle element | Specify the initial state. Only "on" or "off" are supported:
    <span class="wb-toggle" data-toggle='{"state": "on"}'>
| "off" (default): Toggle element initial state is "off" "on": Toggle element initial state is "on"
`stateOn` | CSS class that's added to elements when they are toggled on. | Specify a CSS class name without the leading "."
    <span class="wb-toggle" data-toggle='{"stateOn": "cssClass"}'>
| None (default): Defaults to "on" String: CSS class name
`stateOff` | CSS class that's added to elements when they are toggled off. | Specify a CSS class name without the leading "."
    <span class="wb-toggle" data-toggle='{"stateOff": "cssClass"}'>
| None (default): Defaults to "off" String: CSS class name

## Events

Document the public events that can be used by implementers or developers.

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-toggle` | Triggered manually (e.g., `$( ".wb-toggle" ).trigger( "wb-init.wb-toggle" );`). | Used to manually initialize the Toggle plugin. Note: the toggle plugin will be initialized automatically unless the element is added after the page has already loaded.
`wb-ready.wb-toggle` (v4.0.5+) | Triggered automatically after a toggle initializes. | Used to identify which toggle was initialized (target of the event)
    $( document ).on( "wb-ready.wb-toggle", ".wb-toggle", function( event ) {
    });
    $( ".wb-toggle" ).on( "wb-ready.wb-toggle", function( event ) {
    });
`toggle.wb-toggle` | Triggered manually and automatically by plugin (e.g., `$( ".wb-toggle" ).trigger( "toggle.wb-toggle" );`). | Causes a toggle element to change the toggle state of the elements it controls. Normally triggered by clicking on the toggle element. When triggering this event manually, the data-toggle attribute must be passed as the second argument:
    // Get a reference to the toggle element and its settings
    	var $toggler = $( ".wb-toggle" );
    		settings = $toggler.data( "toggle" );

    	// Trigger the toggle event
    	$toggler.trigger( "toggle.wb-toggle", settings );
`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

Toggle plugin source code on GitHub.

Date de modification :
  2015-04-22