Switch API

Edit on GitHub

The Switch component is a user interface widget for switching/toggling a setting, preference, option, etc.

Creating a Switch

var switchUI = fluid.switchUI(container);

// or

var switchUIWithOptions = fluid.switchUI(container, options);

Parameters

container

The container parameter is a CSS-based selector, single-element jQuery object, or DOM element specifying the containing element for the Switch.

options parameter

The options parameter is an optional collection of name-value pairs that configure the Switch, as described in the Options section below.

Options

General options

Name Description Values Default
selectors

JavaScript object defining CSS-style selectors for important DOM elements. See Selectors for more information.

 The object may contain the following keys:
  • on
  • off
  • control
 
                    
selectors: {
    on: ".flc-switchUI-on",
    off: ".flc-switchUI-off",
    control: ".flc-switchUI-control"
}
strings An object containing text to be used by the switch. These are displayed visually on the screen and/or provided as a label for an assistive technology. The object may contain the following keys:
  • label
  • on
  • off
 
                    
strings: {
    // Specified by implementor
    // text of label to apply the switch, must add to "aria-label" in the attrs block
    label: "",
    on: "on",
    off: "off"
}
attrs An object containing any HTML attributes to be added to the switch control. An object containing any key/value pairs representing valid HTML attributes and their respective values. In particular, an integrator should define a key/value pairing for "aria-label" or "aria-labelledby".
Note: If the switch controls another element on the page, "aria-controls" should be added to indicate the relationship.
 
                    
attrs: {
    role: "switch",
    tabindex: 0
}
model The state of the switch. true is "on", false is "off" 
                    
model: {
    enabled: false
}

Selectors

The selectors option is an object containing CSS-based selectors for the various parts of the Switch. Supported selectors are:

Name Description Default
on Identifies the element for the "on" identifier 
                    
selectors: {
    on: ".flc-switchUI-on"
}
off Identifies the element for the "off" identifier 
                    
selectors: {
    off: ".flc-switchUI-off"
}
selectables Identifies the DOM element that represents the actual UI switch control. 
                    
selectors: {
    control: ".flc-switchUI-control"
}

Styling the Switch

The Switch includes default CSS styles that are applied to its elements. The application of styles is based on known class names. The default class names are described below, and can be used by including the Switch stylesheet:

<link href="components/switch/css/Switch.css" type="text/css" rel="stylesheet" media="all">;
Note: Switch.css is generated from the Switch.styl Stylus file. See the Developing with the Preferences Framework section of the Infusion README for how to build Stylus files.

These styling classes should be added to the markup used by the Switch. To modify the appearance, one can modify the markup and/or override the style declarations applied to the classes.

Default Classes

  • fl-switchUI - Should be added to the switch container.
  • fl-switchUI-text - Should be applied to the "on" and "off" indicators.
  • fl-switchUI-control - Should be applied to the actual switch control.
  • fl-switchUI-controlKnob - Should be applied to the knob of the switch control.

Dependencies

The Switch dependencies can be met by including the infusion-all.js file in the header of the HTML file:

<script type="text/javascript" src="infusion-all.js"></script>

Alternatively, the individual file requirements are:

<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="lib/jquery/ui/js/jquery-ui.js"></script>
<script type="text/javascript" src="framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="framework/core/js/FluidDocument.js"></script>
<script type="text/javascript" src="framework/core/js/FluidIoC.js"></script>
<script type="text/javascript" src="framework/core/js/DataBinding.js"></script>
<script type="text/javascript" src="framework/core/js/FluidView.js"></script>
<script type="text/javascript" src="components/switch/js/Switch.js"></script>

The Switch also requires the following stylesheet:

<link rel="stylesheet" type="text/css" href="components/switch/css/Switch.css" />