---
{
	"title": "Basculer",
	"language": "fr",
	"category": "Plugiciels",
	"categoryfile": "plugins",
	"description": "Plugiciel qui permet un lien à basculer des éléments entre les états activé et désactivé.",
	"altLangPrefix": "toggle",
	"dateModified": "2015-04-22"
}
---
<span class="wb-prettify all-pre hide"></span>

<div lang="en">
	<p><strong>Needs translation</strong></p>
	<section>
		<h2>Purpose</h2>
		<p>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 <a href="https://www.w3.org/TR/wai-aria-practices/#accordion">WAI-ARIA accordion design pattern</a>.</p>
	</section>

	<section>
		<h2>Use when</h2>
		<ul>
			<li>Clicking an element should control the state of itself or other elements on the page (e.g. a button to open/close all <code>&lt;details&gt;</code> elements).</li>
			<li>Elements should change state when the page is printed (<code>&lt;details&gt;</code> elements should be automatically opened for print).</li>
			<li>Accordion widget behaviour is needed.</li>
		</ul>
	</section>

	<section>
		<h2>Do not use when</h2>
		<ul>
			<li>The element being toggled already supports the behaviour natively (e.g. <code>&lt;details&gt;</code> elements).</li>
		</ul>
	</section>

	<section>
		<h2>Working example</h2>
		<p><a href="../../../demos/toggle/toggle-en.html">English example</a></p>
		<p><a href="../../../demos/toggle/toggle-fr.html">French example</a></p>
	</section>

	<section>
		<h2>How to implement</h2>

		<section>
			<h3>Toggle self</h3>
			<p>This is the most basic use of the plugin. It allows an element to toggle itself on and off when clicked.</p>
			<ol>
				<li>Add the <code>wb-toggle</code> CSS class to an element.</li>
			</ol>
			<pre><code>&lt;button type="button" class="wb-toggle"&gt;Toggle&lt;/button&gt;</code></pre>
		</section>

		<section>
			<h3 id="toggle-other">Toggle other elements</h3>
			<p>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.</p>
			<ol>
				<li>Add the <code>wb-toggle</code> CSS class to the toggle element.</li>
				<li>Using the <code>data-toggle</code> attribute, specify the CSS selector of the elements that will have their states toggled.</li>
			</ol>
			<pre><code>&lt;button type="button" class="wb-toggle" data-toggle="{'selector': '.otherElements'}"&gt;Toggle&lt;/button&gt;</code></pre>
		</section>

		<section>
			<h3>Toggle configuration</h3>
			<p>This example expands on <a href="#toggle-other">Toggle other elements</a> by using the plugin's <a href="#config">configuration options</a>.</p>
			<ol>
				<li>Add the <code>wb-toggle</code> CSS class to the toggle element.</li>
				<li>Using the <code>data-toggle</code> data attribute, specify
					<ul>
						<li>the CSS selector of the elements that will have their states toggled,</li>
						<li>the CSS selector of the parent these elements must exist in,</li>
						<li>that toggle is "on" only,</li>
						<li>that elements should be toggled "on" when the page is printed, and</li>
						<li>that the toggle state should be saved between page loads using sessionStorage.</li>
					</ul>
				</li>
			</ol>
			<pre class="linenums"><code>&lt;button type="button" class="wb-toggle" data-toggle="{
		'selector': '.otherElements',
		'parent': '#parentElement',
		'type': 'on',
		'print': 'on',
		'persist': 'session'}"&gt;Toggle&lt;/button&gt;</code></pre>
		</section>

		<section>
			<h3>Grouped Toggle</h3>
			<p>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.</p>
			<ol>
				<li>Add the <code>wb-toggle</code> CSS class to the toggle elements.</li>
				<li>Using the <code>data-toggle</code> attribute, specify the element(s) the toggle element will control, and the group CSS selector.</li>
			</ol>
			<p>The following shows a completed example for button elements that toggle open details elements:</p>
			<pre class="linenums"><code>&lt;button type="button" class="wb-toggle" data-toggle='{"selector": "#toggle1", "group": ".grouped", "type": "on"}'&gt;Example 1&lt;/button&gt;
	&lt;button type="button" class="wb-toggle" data-toggle='{"selector": "#toggle2", "group": ".grouped", "type": "on"}'&gt;Example 2&lt;/button&gt;

	&lt;details id="toggle1" class="grouped"&gt;
		&lt;!-- content --&gt;
	&lt;/details&gt;
	&lt;details id="toggle2" class="grouped"&gt;
		&lt;!-- content --&gt;
	&lt;/details&gt;</code></pre>
		</section>

		<section>
			<h3>Accordion</h3>
			<p>The group toggle feature of the plugin can also be used to create an accordion.</p>
			<ol>
				<li>Wrap all sections of the accordion in parent element with a unique CSS class or ID. <code>&lt;div class="accordion"&gt;</code></li>
				<li>For each accordion section:
					<ul>
						<li>Add the <code>wb-toggle</code> class and <code>data-toggle</code> attribute to the element the user will click to open/close the section.</li>
						<li>Add the <code>tgl-tab</code> class to the element that shows the section's heading.</li>
						<li>Wrap the content in a <code>&lt;div class="tgl-panel"&gt;</code> element.</li>
					</ul>
				</li>
			</ol>
			<p>If details elements are used for the accordion sections, the HTML should look like the following once finished:</p>
			<pre class="linenums"><code>&lt;div class="accordion"&gt;

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

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

	&lt;/div&gt;</code></pre>
		</section>
	</section>

	<section>
		<h2 id="config">Configuration options</h2>
		<p>All configuration options of the plugin are controlled by the <code>data-toggle</code> attribute:</p>
		<table class="table">
			<thead>
				<tr>
					<th>Option</th>
					<th>Description</th>
					<th>How to configure</th>
					<th>Values</th>
				</tr>
			</thead>

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

	<section>
		<h2>Events</h2>
		<p>Document the public events that can be used by implementers or developers.</p>
		<table class="table">
			<thead>
				<tr>
					<th>Event</th>
					<th>Trigger</th>
					<th>What it does</th>
				</tr>
			</thead>
			<tbody>
				<tr>
					<td><code>wb-init.wb-toggle</code></td>
					<td>Triggered manually (e.g., <code>$( ".wb-toggle" ).trigger( "wb-init.wb-toggle" );</code>).</td>
					<td>Used to manually initialize the Toggle plugin. <strong>Note:</strong> the toggle plugin will be initialized automatically unless the element is added after the page has already loaded.</td>
				</tr>
				<tr>
					<td><code>wb-ready.wb-toggle</code> (v4.0.5+)</td>
					<td>Triggered automatically after a toggle initializes.</td>
					<td>Used to identify which toggle was initialized (target of the event)
						<pre><code>$( document ).on( "wb-ready.wb-toggle", ".wb-toggle", function( event ) {
});</code></pre>
						<pre><code>$( ".wb-toggle" ).on( "wb-ready.wb-toggle", function( event ) {
});</code></pre>
					</td>
				</tr>
				<tr>
					<td><code>toggle.wb-toggle</code></td>
					<td>Triggered manually and automatically by plugin (e.g., <code>$( ".wb-toggle" ).trigger( "toggle.wb-toggle" );</code>).</td>
					<td>
						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:
						<pre><code>// 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 );</code></pre>
					</td>
				</tr>
				<tr>
					<td><code>wb-ready.wb</code> (v4.0.5+)</td>
					<td>Triggered automatically when WET has finished loading and executing.</td>
					<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
						<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
					</td>
			</tr>
			</tbody>
		</table>
	</section>

	<section>
		<h2>Source code</h2>
		<p><a href="https://github.com/wet-boew/wet-boew/blob/master/src/plugins/toggle">Toggle plugin source code on GitHub.</a></p>
	</section>
</div>