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

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **dialog** component allows for verification of
   4 user actions, simple data input, and alerts to provide extra information to users.
   5
   6 ## Basic Usage
   7
   8 To use the dialog component, you must be using a browser that supports the [dialog element](http://www.w3.org/TR/2013/CR-html5-20130806/interactive-elements.html#the-dialog-element).
   9 Only Chrome and Opera have native support at the time of writing.
  10 For other browsers you will need to include the [dialog polyfill](https://github.com/GoogleChrome/dialog-polyfill) or create your own.
  11
  12 Once you have dialog support create a dialog element.
  13 The element when using the polyfill **must** be a child of the `body` element.
  14 Within that container, add a content element with the class `mdl-dialog__content`.
  15 Add you content, then create an action container with the class `mdl-dialog__actions`.
  16 Finally for the markup, add your buttons within this container for triggering dialog functions.
  17
  18 Keep in mind, the order is automatically reversed for actions.
  19 Material Design requires that the primary (confirmation) action be displayed last.
  20 So, the first action you create will appear last on the action bar.
  21 This allows for more natural coding and tab ordering while following the specification.
  22
  23 Remember to add the event handlers for your action items.
  24 After your dialog markup is created, add the event listeners to the page to trigger the dialog to show.
  25
  26 For example:
  27
  28 ```javascript
  29   var button = document.querySelector('button');
  30   var dialog = document.querySelector('dialog');
  31   button.addEventListener('click', function() {
  32     dialog.showModal();
  33     /* Or dialog.show(); to show the dialog without a backdrop. */
  34   });
  35 ```
  36
  37 ## Examples
  38
  39 ### Simple Dialog
  40
  41 See this example live in [codepen](http://codepen.io/Garbee/full/EPoaMj/).
  42
  43 ```html
  44 <body>
  45   <button id="show-dialog" type="button" class="mdl-button">Show Dialog</button>
  46   <dialog class="mdl-dialog">
  47     <h4 class="mdl-dialog__title">Allow data collection?</h4>
  48     <div class="mdl-dialog__content">
  49       <p>
  50         Allowing us to collect data will let us get you the information you want faster.
  51       </p>
  52     </div>
  53     <div class="mdl-dialog__actions">
  54       <button type="button" class="mdl-button">Agree</button>
  55       <button type="button" class="mdl-button close">Disagree</button>
  56     </div>
  57   </dialog>
  58   <script>
  59     var dialog = document.querySelector('dialog');
  60     var showDialogButton = document.querySelector('#show-dialog');
  61     if (! dialog.showModal) {
  62       dialogPolyfill.registerDialog(dialog);
  63     }
  64     showDialogButton.addEventListener('click', function() {
  65       dialog.showModal();
  66     });
  67     dialog.querySelector('.close').addEventListener('click', function() {
  68       dialog.close();
  69     });
  70   </script>
  71 </body>
  72 ```
  73
  74 ### Dialog with full width actions
  75
  76 See this example live in [codepen](http://codepen.io/Garbee/full/JGMowG/).
  77
  78 ```html
  79 <body>
  80   <button type="button" class="mdl-button show-modal">Show Modal</button>
  81   <dialog class="mdl-dialog">
  82     <div class="mdl-dialog__content">
  83       <p>
  84         Allow this site to collect usage data to improve your experience?
  85       </p>
  86     </div>
  87     <div class="mdl-dialog__actions mdl-dialog__actions--full-width">
  88       <button type="button" class="mdl-button">Agree</button>
  89       <button type="button" class="mdl-button close">Disagree</button>
  90     </div>
  91   </dialog>
  92   <script>
  93     var dialog = document.querySelector('dialog');
  94     var showModalButton = document.querySelector('.show-modal');
  95     if (! dialog.showModal) {
  96       dialogPolyfill.registerDialog(dialog);
  97     }
  98     showModalButton.addEventListener('click', function() {
  99       dialog.showModal();
 100     });
 101     dialog.querySelector('.close').addEventListener('click', function() {
 102       dialog.close();
 103     });
 104   </script>
 105 </body>
 106 ```
 107
 108 ## CSS Classes
 109
 110 ### Blocks
 111
 112 | MDL Class | Effect | Remarks |
 113 |-----------|--------|---------|
 114 | `mdl-dialog` | Defines the container of the dialog component. | Required on dialog container. |
 115
 116 ### Elements
 117
 118 | MDL Class | Effect | Remarks |
 119 |-----------|--------|---------|
 120 | `mdl-dialog__title` | Defines the title container in the dialog. | Optional on title container. |
 121 | `mdl-dialog__content` | Defines the content container of the dialog. | Required on content container. |
 122 | `mdl-dialog__actions` | Defines the actions container in the dialog. | Required on action container. |
 123
 124 ### Modifiers
 125
 126 | MDL Class | Effect | Remarks |
 127 |-----------|--------|---------|
 128 | `mdl-dialog__actions--full-width` | Modifies the actions to each take the full width of the container. This makes each take their own line. | Optional on action container. |