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

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **data-table** component is an enhanced version of the standard HTML `<table>`. A data-table consists of rows and columns of well-formatted data, presented with appropriate user interaction capabilities.
   4
   5 Tables are a ubiquitous 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 data-table component's [Material Design specifications page](http://www.google.com/design/spec/components/data-tables.html) for details.
   6
   7 The available row/column/cell types in a data-table are mostly self-formatting; that is, once the data-table is defined, the individual cells require very little specific attention. For example, the rows exhibit shading behavior on mouseover and selection, numeric values are automatically formatted by default, and the addition of a single class makes the table rows individually or collectively selectable. This makes the data-table component convenient and easy to code for the developer, as well as attractive and intuitive for the user.
   8
   9 ### To include an MDL **data-table** component:
  10
  11 &nbsp;1. Code a `<table>` element. Include `<thead>` and `<tbody>` elements to hold the title and data rows, respectively.
  12 ```html
  13 <table>
  14   <thead>
  15   </thead>
  16   <tbody>
  17   </tbody>
  18 </table>
  19 ```
  20
  21 &nbsp;2. Add one or more MDL classes, separated by spaces, to the table using the `class` attribute.
  22 ```html
  23 <table class="mdl-data-table mdl-js-data-table">
  24   <thead>
  25   </thead>
  26   <tbody>
  27   </tbody>
  28 </table>
  29 ```
  30
  31 &nbsp;2. Inside the `<thead>`, code exactly one table row `<tr>` containing one table header cell `<th>` for each column, and include the desired text in the header cells. To ensure proper header alignment, add the "non-numeric" MDL class to the header cell of text-only columns. (Data cells are formatted as numeric by default.)
  32 ```html
  33 <table class="mdl-data-table mdl-js-data-table">
  34   <thead>
  35     <tr>
  36       <th class="mdl-data-table__cell--non-numeric">Name</th>
  37       <th>Age</th>
  38       <th>ID Number</th>
  39     </tr>
  40   </thead>
  41   <tbody>
  42   </tbody>
  43 </table>
  44 ```
  45
  46 &nbsp;3. Inside the `<tbody>`, code one table row `<tr>` for each data row and one table data cell `<td>` for each column in the row. As with the header cells, add the "non-numeric" MDL class to text-only data cells to ensure proper alignment.
  47 ```html
  48 <table class="mdl-data-table mdl-js-data-table">
  49   <thead>
  50     <tr>
  51       <th class="mdl-data-table__cell--non-numeric">Name</th>
  52       <th>Age</th>
  53       <th>ID Number</th>
  54     </tr>
  55   </thead>
  56   <tbody>
  57     <tr>
  58       <td class="mdl-data-table__cell--non-numeric">Don Aubrey</td>
  59       <td>25</td>
  60       <td>49021</td>
  61     </tr>
  62     <tr>
  63       <td class="mdl-data-table__cell--non-numeric">Sophia Carson</td>
  64       <td>32</td>
  65       <td>10258</td>
  66     </tr>
  67     <tr>
  68       <td class="mdl-data-table__cell--non-numeric">Steve Moreno</td>
  69       <td>29</td>
  70       <td>12359</td>
  71     </tr>
  72   </tbody>
  73 </table>
  74 ```
  75
  76 The data-table component is ready for use.
  77
  78 #### Examples
  79
  80 A data-table with a "master" select checkbox and individual row select checkboxes.
  81 ```html
  82 <table class="mdl-data-table mdl-js-data-table mdl-data-table--selectable">
  83   <thead>
  84     <tr>
  85       <th class="mdl-data-table__cell--non-numeric">Material</th>
  86       <th>Quantity</th>
  87       <th>Unit price</th>
  88     </tr>
  89   </thead>
  90   <tbody>
  91     <tr>
  92       <td class="mdl-data-table__cell--non-numeric">Acrylic (Transparent)</td>
  93       <td>250</td>
  94       <td>$2.90</td>
  95     </tr>
  96     <tr>
  97       <td class="mdl-data-table__cell--non-numeric">Plywood (Birch)</td>
  98       <td>50</td>
  99       <td>$1.25</td>
 100     </tr>
 101     <tr>
 102       <td class="mdl-data-table__cell--non-numeric">Laminate (Gold on Blue)</td>
 103       <td>10</td>
 104       <td>$12.35</td>
 105     </tr>
 106   </tbody>
 107 </table>
 108 ```
 109
 110 A data-table without select checkboxes containing mostly text data.
 111 ```html
 112 <table class="mdl-data-table mdl-js-data-table">
 113   <thead>
 114     <tr>
 115       <th class="mdl-data-table__cell--non-numeric">Name</th>
 116       <th class="mdl-data-table__cell--non-numeric">Nickname</th>
 117       <th>Age</th>
 118       <th class="mdl-data-table__cell--non-numeric">Living?</th>
 119     </tr>
 120   </thead>
 121   <tbody>
 122     <tr>
 123       <td class="mdl-data-table__cell--non-numeric">John Lennon</td>
 124       <td class="mdl-data-table__cell--non-numeric">The smart one</td>
 125       <td>40</td>
 126       <td class="mdl-data-table__cell--non-numeric">No</td>
 127     </tr>
 128     <tr>
 129       <td class="mdl-data-table__cell--non-numeric">Paul McCartney</td>
 130       <td class="mdl-data-table__cell--non-numeric">The cute one</td>
 131       <td>73</td>
 132       <td class="mdl-data-table__cell--non-numeric">Yes</td>
 133     </tr>
 134     <tr>
 135       <td class="mdl-data-table__cell--non-numeric">George Harrison</td>
 136       <td class="mdl-data-table__cell--non-numeric">The shy one</td>
 137       <td>58</td>
 138       <td class="mdl-data-table__cell--non-numeric">No</td>
 139     </tr>
 140     <tr>
 141       <td class="mdl-data-table__cell--non-numeric">Ringo Starr</td>
 142       <td class="mdl-data-table__cell--non-numeric">The funny one</td>
 143       <td>74</td>
 144       <td class="mdl-data-table__cell--non-numeric">Yes</td>
 145     </tr>
 146   </tbody>
 147 </table>
 148 ```
 149
 150 ## Configuration options
 151
 152 The MDL CSS classes apply various predefined visual and behavioral enhancements to the data-table. The table below lists the available classes and their effects.
 153
 154 | MDL class | Effect | Remarks |
 155 |-----------|--------|---------|
 156 | `mdl-data-table` | Defines table as an MDL component | Required on table element|
 157 | `mdl-js-data-table` | Assigns basic MDL behavior to table | Required on table element|
 158 | `mdl-data-table--selectable` | Applies all/individual selectable behavior (checkboxes) | Optional; goes on table element |
 159 | `mdl-data-table__header--sorted-ascending` | Applies visual styling to indicate the column is sorted in ascending order | Optional; goes on table header (`th`) |
 160 | `mdl-data-table__header--sorted-descending` | Applies visual styling to indicate the column is sorted in descending order | Optional; goes on table header (`th`) |
 161 | `mdl-data-table__cell--non-numeric` | Applies text formatting to data cell | Optional; goes on both table header and table data cells |
 162 | (none) | Applies numeric formatting to header or data cell (default) |  |