third_party/ot-br-posix/repo/third_party/mdl/repo/src/icon-toggle/README.md

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **icon-toggle** component is an enhanced version of the standard HTML `<input type="checkbox">` element. An icon-toggle consists of a user defined icon that indicates, by visual highlighting, a binary condition that will be set or unset when the user clicks or touches it. Like checkboxes, icon-toggles may appear individually or in groups, and can be selected and deselected individually.
   4
   5 Icon toggles, particularly as a replacement for certain checkboxes, can be a valuable feature in user interfaces, regardless of a site's content or function. Their design and use is therefore an important factor in the overall user experience. See the icon-toggle component's [Material Design specifications page](http://www.google.com/design/spec/components/buttons.html#buttons-other-buttons) for details.
   6
   7 The icon-toggle component can have a more customized visual look than a standard checkbox, and may be initially or programmatically *disabled*.
   8
   9 ### To include an MDL **icon-toggle** component:
  10
  11 &nbsp;1. Code a `<label>` element and give it a `for` attribute whose value is the unique id of the icon-toggle it will contain.
  12 ```html
  13 <label for="icon-toggle-1">
  14 ...
  15 </label>
  16 ```
  17 &nbsp;2. Inside the label, code an `<input>` element and give it a `type` attribute whose value is `"checkbox"`. Also give it an `id` attribute whose value matches the label's `for` attribute value.
  18 ```html
  19 <label for="icon-toggle-1">
  20   <input type="checkbox" id="icon-toggle-1">
  21 </label>
  22 ```
  23 &nbsp;3. Also inside the label, after the input element, code an `<i>` element containing the icon-toggle's desired icon.
  24 ```html
  25 <label for="icon-toggle-1">
  26   <input type="checkbox" id="icon-toggle-1">
  27   <i class="mdl-icon-toggle__label material-icons">format_bold</i>
  28 </label>
  29 ```
  30 &nbsp;4. Add one or more MDL classes, separated by spaces, to the label and input elements, using the `class` attribute.
  31 ```html
  32 <label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1">
  33   <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input">
  34   <i class="mdl-icon-toggle__label material-icons">format_bold</i>
  35 </label>
  36 ```
  37
  38 The icon-toggle component is ready for use.
  39
  40 #### Example
  41
  42 An icon-toggle with a ripple click effect.
  43
  44 ```html
  45 <label class="mdl-icon-toggle mdl-js-icon-toggle mdl-js-ripple-effect" for="icon-toggle-1">
  46   <input type="checkbox" id="icon-toggle-1" class="mdl-icon-toggle__input">
  47   <i class="mdl-icon-toggle__label material-icons">format_bold</i>
  48 </label>
  49 ```
  50
  51 ## Configuration options
  52
  53 The MDL CSS classes apply various predefined visual and behavioral enhancements to the icon-toggle. The table below lists the available classes and their effects.
  54
  55 | MDL class | Effect | Remarks |
  56 |-----------|--------|---------|
  57 | `mdl-icon-toggle` | Defines label as an MDL component | Required on label element|
  58 | `mdl-js-icon-toggle` | Assigns basic MDL behavior to label | Required on label element |
  59 | `mdl-icon-toggle__input` | Applies basic MDL behavior to icon-toggle | Required on input element (icon-toggle) |
  60 | `mdl-icon-toggle__label` | Applies basic MDL behavior to caption | Required on i element (icon) |
  61 | `mdl-js-ripple-effect` | Applies *ripple* click effect | Optional; goes on label element, not input element (icon-toggle) |
  62
  63 >**Note:** Disabled versions of all available input types are provided, and are invoked with the standard HTML boolean attribute `disabled`. `<input type="checkbox" id="icon-toggle-5" class="mdl-icon-toggle__input" disabled>`
  64 >This attribute may be added or removed programmatically via scripting.