carbon-components/src/components/content-switcher/README.md

Carbon Components is a component library for IBM Cloud

### SCSS

#### Modifiers

| Name                              | Description                                                  |
| --------------------------------- | ------------------------------------------------------------ |
| `.bx--content-switcher--selected` | Applies the "selected" styles to the content-switcher button |

### Javascript

#### Getting component class reference

##### ES2015

```javascript
import { ContentSwitcher } from 'carbon-components';
```

##### With pre-build bundle (`carbon-components.min.js`)

```javascript
var ContentSwitcher = CarbonComponents.ContentSwitcher;
```

#### Instantiating

```javascript
// `#my-content-switcher` is an element with `[data-content-switcher]` attribute
ContentSwitcher.create(document.getElementById('my-content-switcher'));
```

#### Public Methods

| Name        | Params                                        | Description                                                                                                                                                                                   |
| ----------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `setActive` | `item`: `HTMLElement`, `callback`: `Function` | Uses `data-target` attribute to show a content panel using the given CSS selector. Non-active targets will be hidden. You can also pass in an optional callback function, see FAQ for details |
| `release`   |                                               | Deletes the instance and removes document event listeners                                                                                                                                     |

##### Example - Changing the active item

```javascript
// `#my-content-switcher` is an element with `[data-content-switcher]` attribute
var contentSwitcherInstance = ContentSwitcher.create(document.getElementById('my-content-switcher'));
// `#my-content-switcher-btn-1` is one of the `<button>`s with `bx--content-switcher-btn` class
contentSwitcherInstance.setActive(document.getElementById('my-content-switcher-btn-1'));
```

#### Options

| Option                | Default Selector                                 | Description                                                        |
| --------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
| `selectorInit`        | `[data-content-switcher]`                        | The CSS selector to find content-switcher                          |
| `selectorButton`      | `input[type="radio"], .bx--content-switcher-btn` | The CSS selector to find the content-switcher buttons              |
| `classActive`         | `bx--content-switcher--selected`                 | The className for a selected button                                |
| `eventBeforeSelected` | `content-switcher-beingselected`                 | Custom event fired before a button is selected in content-switcher |
| `eventAfterSelected`  | `content-switcher-selected`                      | Custom event fired after a button is selected in content-switcher  |

#### Events

| Event Name                       | Description                                                        |
| -------------------------------- | ------------------------------------------------------------------ |
| `content-switcher-beingselected` | Custom event fired before a button is selected in content-switcher |
| `content-switcher-selected`      | Custom event fired after a button is selected in content-switcher  |

##### Example

Preventing a content switcher item from being selected in a certain condition

```javascript
document.addEventListener('content-switcher-beingselected', function(evt) {
  if (!myApplication.shouldContentSwitcherItemBeSelected(evt.target)) {
    evt.preventDefault();
  }
});
```

##### Example

Notifying events of all content switcher items being selected to an analytics library

```javascript
document.addEventListener('content-switcher-selected', function(evt) {
  myAnalyticsLibrary.send({
    action: 'Content switcher item selected',
    id: evt.target.id,
  });
});
```

#### Classes

| Name                             | Description                         |
| -------------------------------- | ----------------------------------- |
| `bx--content-switcher--selected` | The className for a selected button |

### FAQ

#### Preset an active button and panel with HTML

While SCSS and JS are setup, you can configure Content Switcher and its associated content through the HTML.

Each `bx--content-switcher-btn` has a `data-target` value with a selector for a panel element.
When one of these buttons is clicked, then it will show the panel that the `data-target` is pointing to.

For example,

The first button has a `data-target` pointing to `.demo-panel--opt-1`.
When clicking the first button, the JavaScript will find the DOM element using the given `data-target` selector and display it while hiding all other panels using the `hidden` attribute.

Below is an HTML setup for Content Switcher that will do the following:

- Select the first button by default (as indicated by `bx--content-switcher--selected` class)
- Show the `<div class="demo--panel--opt-1">` element
- Hide the other elements

```html
<div data-content-switcher class="bx--content-switcher">
  <button class="bx--content-switcher-btn bx--content-switcher--selected" data-target=".demo--panel--opt-1">Option 1</button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">Option 2</button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">Option 3</button>
</div>
<div class="demo--panel--opt-1">Show Option 1</div>
<div class="demo--panel--opt-2" hidden>Show Option 2</div>
<div class="demo--panel--opt-3" hidden>Show Option 3</div>
```

#### Preset an active button and panel with JavaScript

Use `setActive` class method to preset the selection on a Content Switcher; doing this will avoid manually adding `bx--content-switcher--selected` modifier class and `hidden` attributes on HTML.

```html
<div data-content-switcher id="my-content-switcher" class="bx--content-switcher">
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-1">Option 1</button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">Option 2</button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">Option 3</button>
</div>
<div class="demo--panel--opt-1">Show Option 1</div>
<div class="demo--panel--opt-2">Show Option 2</div>
<div class="demo--panel--opt-3">Show Option 3</div>
```

```js
// Get HTMLelement for button to preselect it with setActive
const button = document.querySelector('[data-target=".demo--panel--opt-2"]');
// Initialize an instance of ContentSwitcher with init(), create(element) or new ContentSwitcher(element)
ContentSwitcher.init();
// Grab an ContentSwitcher instance
const instance = ContentSwitcher.components.get(document.getElementById('my-content-switcher'));
// Use setActive
instance.setActive(button);
```

The `setActive` method also takes an optional `callback` function parameter. The most typical example of using this is acting on a newly selected content-switcher button.

```js
contentSwitcher.setActive(button, function(error, item) {
  if (!error) {
    // Having no error means that content switching is not canceled, so go on…
    item.ownerDocument
      .querySelector(item.dataset.target)
      .querySelector('input')
      .focus(); // `item` is the newly selected button
  }
});
```

#### Using buttons or anchor elements are both fine

Content Switcher can be implemented with either `<button>` or `<a>` elements for its click targets.
Both uses of HTML will render the same visual styles and interactions.

```html
<div data-content-switcher class="bx--content-switcher">
  <a href="javascript:void(0)" class="bx--content-switcher-btn bx--content-switcher--selected" data-target=".demo--panel--opt-1"
    >Option 1</a
  >
  <a href="javascript:void(0)" class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">Option 2</a>
  <a href="javascript:void(0)" class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">Option 3</a>
</div>
<div data-content-switcher class="bx--content-switcher">
  <button class="bx--content-switcher-btn bx--content-switcher--selected" data-target=".demo--panel--opt-1">Option 1</button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">Option 2</button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">Option 3</button>
</div>
```