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

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **grid** component is a simplified method for laying out content for multiple screen sizes. It reduces the usual coding burden required to correctly display blocks of content in a variety of display conditions.
   4
   5 The MDL grid is defined and enclosed by a container element. A grid has 12 columns in the desktop screen size, 8 in the tablet size, and 4 in the phone size, each size having predefined margins and gutters. Cells are laid out sequentially in a row, in the order they are defined, with some exceptions:
   6
   7 - If a cell doesn't fit in the row in one of the screen sizes, it flows into the following line.
   8 - If a cell has a specified column size equal to or larger than the number of columns for the current screen size, it takes up the entirety of its row.
   9
  10 You can set a maximum grid width, after which the grid stays centered with padding on either side, by setting its `max-width` CSS property.
  11
  12 Grids are a fairly new and non-standardized feature in most user interfaces, and provide users with a way to view content in an organized manner that might otherwise be difficult to understand or retain. Their design and use is an important factor in the overall user experience.
  13
  14 ### To include an MDL **grid** component:
  15
  16 &nbsp;1. Code a `<div>` element; this is the "outer" container, intended to hold all of the grid's cells. Style the div as desired (colors, font size, etc.).
  17 ```html
  18 <div>
  19 </div>
  20 ```
  21 &nbsp;2. Add the `mdl-grid` MDL class to the div using the `class` attribute.
  22 ```
  23 <div class="mdl-grid">
  24 </div>
  25 ```
  26 &nbsp;3. For each cell, code one "inner" div, including the text to be displayed.
  27 ```html
  28 <div class="mdl-grid">
  29   <div>Content</div>
  30   <div>goes</div>
  31   <div>here</div>
  32 </div>
  33 ```
  34 &nbsp;4. Add the `mdl-cell` class and an `mdl-cell--COLUMN-col` class, where COLUMN specifies the column size for the cell, to the "inner" divs using the `class` attribute.
  35 ```html
  36 <div class="mdl-grid">
  37   <div class="mdl-cell mdl-cell--4-col">Content</div>
  38   <div class="mdl-cell mdl-cell--4-col">goes</div>
  39   <div class="mdl-cell mdl-cell--4-col">here</div>
  40 </div>
  41 ```
  42 &nbsp;5. Optionally add an `mdl-cell--COLUMN-col-DEVICE` class, where COLUMN specifies the column size for the cell on a specific device, and DEVICE specifies the device type.
  43 ```html
  44 <div class="mdl-grid">
  45   <div class="mdl-cell mdl-cell--4-col mdl-cell--8-col-tablet">Content</div>
  46   <div class="mdl-cell mdl-cell--4-col mdl-cell--8-col-tablet">goes</div>
  47   <div class="mdl-cell mdl-cell--4-col mdl-cell--8-col-tablet">here</div>
  48 </div>
  49 ```
  50
  51 The grid component is ready for use.
  52
  53 #### Examples
  54
  55 A grid with five cells of column size 1.
  56 ```html
  57 <div class="mdl-grid">
  58   <div class="mdl-cell mdl-cell--1-col">CS 1</div>
  59   <div class="mdl-cell mdl-cell--1-col">CS 1</div>
  60   <div class="mdl-cell mdl-cell--1-col">CS 1</div>
  61   <div class="mdl-cell mdl-cell--1-col">CS 1</div>
  62   <div class="mdl-cell mdl-cell--1-col">CS 1</div>
  63 </div>
  64 ```
  65
  66 A grid with three cells, one of column size 6, one of column size 4, and one of column size 2.
  67 ```html
  68 <div class="mdl-grid">
  69   <div class="mdl-cell mdl-cell--6-col">CS 6</div>
  70   <div class="mdl-cell mdl-cell--4-col">CS 4</div>
  71   <div class="mdl-cell mdl-cell--2-col">CS 2</div>
  72 </div>
  73 ```
  74
  75 A grid with three cells of column size 6 that will display as column size 8 on a tablet device.
  76 ```html
  77 <div class="mdl-grid">
  78   <div class="mdl-cell mdl-cell--6-col mdl-cell--8-col-tablet">CS 6 (8 on tablet)</div>
  79   <div class="mdl-cell mdl-cell--6-col mdl-cell--8-col-tablet">CS 6 (8 on tablet)</div>
  80   <div class="mdl-cell mdl-cell--6-col mdl-cell--8-col-tablet">CS 6 (8 on tablet)</div>
  81 </div>
  82 ```
  83
  84 A grid with four cells of column size 2 that will display as column size 4 on a phone device.
  85
  86 ```html
  87 <div class="mdl-grid">
  88   <div class="mdl-cell mdl-cell--2-col mdl-cell--4-col-phone">CS 2 (4 on phone)</div>
  89   <div class="mdl-cell mdl-cell--2-col mdl-cell--4-col-phone">CS 2 (4 on phone)</div>
  90   <div class="mdl-cell mdl-cell--2-col mdl-cell--4-col-phone">CS 2 (4 on phone)</div>
  91   <div class="mdl-cell mdl-cell--2-col mdl-cell--4-col-phone">CS 2 (4 on phone)</div>
  92 </div>
  93 ```
  94
  95 ## Configuration options
  96
  97 The MDL CSS classes apply various predefined visual enhancements and behavioral effects to the grid. The table below lists the available classes and their effects.
  98
  99 | MDL class | Effect | Remarks |
 100 |-----------|--------|---------|
 101 | `mdl-grid` | Defines a container as an MDL grid component | Required on "outer" div element |
 102 | `mdl-cell` | Defines a container as an MDL cell | Required on "inner" div elements |
 103 | `mdl-grid--no-spacing` | Modifies the grid cells to have no margin between them. | Optional on grid container. |
 104 | `mdl-cell--N-col` | Sets the column size for the cell to N | N is 1-12 inclusive, defaults to 4; optional on "inner" div elements|
 105 | `mdl-cell--N-col-desktop` | Sets the column size for the cell to N in desktop mode only | N is 1-12 inclusive; optional on "inner" div elements|
 106 | `mdl-cell--N-col-tablet` | Sets the column size for the cell to N in tablet mode only | N is 1-8 inclusive; optional on "inner" div elements|
 107 | `mdl-cell--N-col-phone` | Sets the column size for the cell to N in phone mode only | N is 1-4 inclusive; optional on "inner" div elements|
 108 | `mdl-cell--N-offset` | Adds N columns of whitespace before the cell | N is 1-11 inclusive; optional on "inner" div elements|
 109 | `mdl-cell--N-offset-desktop` | Adds N columns of whitespace before the cell in desktop mode | N is 1-11 inclusive; optional on "inner" div elements|
 110 | `mdl-cell--N-offset-tablet` | Adds N columns of whitespace before the cell in tablet mode | N is 1-7 inclusive; optional on "inner" div elements|
 111 | `mdl-cell--N-offset-phone` | Adds N columns of whitespace before the cell in phone mode | N is 1-3 inclusive; optional on "inner" div elements|
 112 | `mdl-cell--order-N` | Reorders cell to position N | N is 1-12 inclusive; optional on "inner" div elements|
 113 | `mdl-cell--order-N-desktop` | Reorders cell to position N when in desktop mode | N is 1-12 inclusive; optional on "inner" div elements|
 114 | `mdl-cell--order-N-tablet` | Reorders cell to position N when in tablet mode | N is 1-12 inclusive; optional on "inner" div elements|
 115 | `mdl-cell--order-N-phone` | Reorders cell to position N when in phone mode | N is 1-12 inclusive; optional on "inner" div elements|
 116 | `mdl-cell--hide-desktop` | Hides the cell when in desktop mode | Optional on "inner" div elements |
 117 | `mdl-cell--hide-tablet` | Hides the cell when in tablet mode | Optional on "inner" div elements |
 118 | `mdl-cell--hide-phone` | Hides the cell when in phone mode | Optional on "inner" div elements |
 119 | `mdl-cell--stretch` | Stretches the cell vertically to fill the parent | Default; optional on "inner" div elements |
 120 | `mdl-cell--top` | Aligns the cell to the top of the parent | Optional on "inner" div elements |
 121 | `mdl-cell--middle` | Aligns the cell to the middle of the parent | Optional on "inner" div elements |
 122 |`mdl-cell--bottom` | Aligns the cell to the bottom of the parent | Optional on "inner" div elements |