Basculer
Vous cherchez la BOEW v3.1?
La BOEW v4.0 est maintenant la version courrante. La version de la page actuelle pour la BOEW v3.1 a été déplacée.
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.
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
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.
- 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.
- Add the wb-toggle CSS class to the toggle element.
- 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.
- Add the wb-toggle CSS class to the toggle element.
- 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.
- Add the wb-toggle CSS class to the toggle elements.
- 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.
- Wrap all sections of the accordion in parent element with a unique CSS class or ID.
<div class="accordion">
- 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. |
|
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. |
|
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. |
|
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: |
|
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: |
|
type | Causes a toggle element to only turn the elements it controls on or off. | Specify the type. Only "on" or "off" are supported: |
|
stateOn | CSS class that's added to elements when they are toggled on. | Specify a CSS class name without the leading "." |
|
stateOff | CSS class that's added to elements when they are toggled off. | Specify a CSS class name without the leading "." |
|
Events
Document the public events that can be used by implementers or developers.
Event | Trigger | What it does |
---|---|---|
wb-init.wb-toggle | Triggered manually. | Initializes the plugin. Note: the toggle plugin will be initialized automatically unless the element is added after the page has already loaded. |
toggle.wb-toggle | Triggered manually and by plugin. | 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: |
Source code
- Date de modification :