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

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **radio** component is an enhanced version of the standard HTML `<input type="radio">`, or "radio button" element. A radio button consists of a small circle and, typically, text that clearly communicates a condition that will be set when the user clicks or touches it. Radio buttons always appear in groups of two or more and, while they can be individually selected, can only be deselected by selecting a different radio button in the same group (which deselects all other radio buttons in the group). The MDL radio component allows you to add display and click effects.
   4
   5 Radio buttons are a common feature of most 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 radio component's [Material Design specifications page](https://www.google.com/design/spec/components/selection-controls.html#selection-controls-radio-button) for details.
   6
   7 The enhanced radio component has a more vivid visual look than a standard radio button, and may be initially or programmatically *disabled*.
   8
   9 ### To include an MDL **radio** component:
  10
  11 &nbsp;1. Code a `<label>` element and give it a `for` attribute whose value is the unique id of the radio button it will contain. The `for` attribute is optional when the `<input>` element is contained inside the `<label>` element, but is recommended for clarity.
  12 ```html
  13 <label for="radio1">
  14 ...
  15 </label>
  16 ```
  17 &nbsp;2. Inside the label, code an `<input>` element and give it a `type` attribute whose value is `"radio"`. Also give it an `id` attribute whose value matches the label's `for` attribute value, and a `name` attribute whose value identifies the radio button group. Optionally, give it a `value` attribute whose value provides some information about the radio button for scripting purposes.
  18 ```html
  19 <label for="radio1">
  20   <input type="radio" id="radio1" name="flash" value="on">
  21 </label>
  22 ```
  23 &nbsp;3. Also inside the label, after the radio button, code a `<span>` element containing the radio button's text caption.
  24 ```html
  25 <label for="radio1">
  26   <input type="radio" id="radio1" name="flash" value="on">
  27   <span>Always on</span>
  28 </label>
  29 ```
  30 &nbsp;4. Add one or more MDL classes, separated by spaces, to the label, checkbox, and caption using the `class` attribute.
  31 ```html
  32 <label for="radio1" class="mdl-radio mdl-js-radio">
  33   <input type="radio" id="radio1" name="flash" value="on" class="mdl-radio__button">
  34   <span class="mdl-radio__label">Always on</span>
  35 </label>
  36 ```
  37 &nbsp;5. Repeat steps 1 through 4 for the other radio components in the group. For each one:
  38 * on the `label` element, specify a unique `for` attribute value
  39 * on the `input` element, specify an `id` attribute value that matches its `label` element's `for` attribute value
  40 * on the `input` element, specify the same `name` attribute value for all radio components in the group
  41 * optionally, on the `input` element, specify a unique `value` attribute value
  42
  43 The radio components are ready for use.
  44
  45 #### Example
  46
  47 A group of radio buttons to control a camera's flash setting.
  48 ```html
  49 <label class="mdl-radio mdl-js-radio mdl-js-ripple-effect" for="flash1">
  50   <input checked class="mdl-radio__button" id="flash1" name="flash" type="radio"
  51    value="on">
  52   <span class="mdl-radio__label">Always on</span>
  53 </label>
  54 <label class="mdl-radio mdl-js-radio mdl-js-ripple-effect" for="flash2">
  55   <input class="mdl-radio__button" id="flash2" name="flash" type="radio" value="off">
  56   <span class="mdl-radio__label">Always off</span>
  57 </label>
  58 <label class="mdl-radio mdl-js-radio mdl-js-ripple-effect" for="flash3">
  59   <input class="mdl-radio__button" id="flash3" name="flash" type="radio" value="auto">
  60   <span class="mdl-radio__label">Automatic</span>
  61 </label>
  62 ```
  63 ## Configuration options
  64
  65 The MDL CSS classes apply various predefined visual and behavioral enhancements to the radio button. The table below lists the available classes and their effects.
  66
  67 | MDL class | Effect | Remarks |
  68 |-----------|--------|---------|
  69 | `mdl-radio` | Defines label as an MDL component | Required on label element|
  70 | `mdl-js-radio` | Assigns basic MDL behavior to label | Required on label element |
  71 | `mdl-radio__button` | Applies basic MDL behavior to radio | Required on input element (radio button) |
  72 | `mdl-radio__label` | Applies basic MDL behavior to caption | Required on span element (caption) |
  73 | `mdl-js-ripple-effect` | Applies *ripple* click effect | Optional; goes on label element, not input element (radio button) |
  74
  75 >**Note:** Disabled versions of all the available radio button types are provided, and are invoked with the standard HTML boolean attribute `disabled`. `<input type="radio" id="radio5" name="flash" class="mdl-radio__button" disabled>`
  76 >This attribute may be added or removed programmatically via scripting.