Copybara bot | be50d49 | 2023-11-30 00:16:42 +0100 | [diff] [blame^] | 1 | |
| 2 | |
| 3 | |
| 4 | <h2 id="introduction">Introduction</h2> |
| 5 | <p>The Material Design Lite (MDL) <strong>snackbar</strong> component is a container used to notify a user of an operation's status. |
| 6 | It displays at the bottom of the screen. |
| 7 | A snackbar may contain an action button to execute a command for the user. |
| 8 | Actions should undo the committed action or retry it if it failed for example. |
| 9 | Actions should not be to close the snackbar. |
| 10 | By not providing an action, the snackbar becomes a <strong>toast</strong> component.</p> |
| 11 | <h2 id="basic-usage-">Basic Usage:</h2> |
| 12 | <p>Start a snackbar with a container div element. |
| 13 | On that container define the <code>mdl-js-snackbar</code> and <code>mdl-snackbar</code> classes. |
| 14 | It is also beneficial to add the aria live and atomic values to this container.</p> |
| 15 | <p>Within the container create a container element for the message. |
| 16 | This element should have the class <code>mdl-snackbar__text</code>. |
| 17 | Leave this element empty! |
| 18 | Text is added when the snackbar is called to be shown.</p> |
| 19 | <p>Second in the container, add a button element. |
| 20 | This element should have the class <code>mdl-snackbar__action</code>. |
| 21 | It is recommended to set the type to button to make sure no forms get submitted by accident. |
| 22 | Leave the text content empty here as well! |
| 23 | Do not directly apply any event handlers.</p> |
| 24 | <p>You now have complete markup for the snackbar to function. |
| 25 | All that is left is within your JavaScript to call the <code>showSnackbar</code> method on the snackbar container. |
| 26 | This takes a <a href="#data-object">plain object</a> to configure the snackbar content appropriately. |
| 27 | You may call it multiple consecutive times and messages will stack.</p> |
| 28 | <h2 id="examples">Examples</h2> |
| 29 | <p>All snackbars should be shown through the same element.</p> |
| 30 | <h4 id="markup-">Markup:</h4> |
| 31 | <pre><code class="lang-html"><div aria-live="assertive" aria-atomic="true" aria-relevant="text" class="mdl-snackbar mdl-js-snackbar"> |
| 32 | <div class="mdl-snackbar__text"></div> |
| 33 | <button type="button" class="mdl-snackbar__action"></button> |
| 34 | </div> |
| 35 | </code></pre> |
| 36 | <blockquote> |
| 37 | <p>Note: In this example there are a few aria attributes for accessibility. Please modify these as-needed for your site.</p> |
| 38 | </blockquote> |
| 39 | <h3 id="snackbar">Snackbar</h3> |
| 40 | <pre><code class="lang-javascript">var notification = document.querySelector('.mdl-js-snackbar'); |
| 41 | var data = { |
| 42 | message: 'Message Sent', |
| 43 | actionHandler: function(event) {}, |
| 44 | actionText: 'Undo', |
| 45 | timeout: 10000 |
| 46 | }; |
| 47 | notification.MaterialSnackbar.showSnackbar(data); |
| 48 | </code></pre> |
| 49 | <h3 id="toast">Toast</h3> |
| 50 | <pre><code class="lang-javascript">var notification = document.querySelector('.mdl-js-snackbar'); |
| 51 | notification.MaterialSnackbar.showSnackbar( |
| 52 | { |
| 53 | message: 'Image Uploaded' |
| 54 | } |
| 55 | ); |
| 56 | </code></pre> |
| 57 | <h2 id="css-classes">CSS Classes</h2> |
| 58 | <h3 id="blocks">Blocks</h3> |
| 59 | <table> |
| 60 | <thead> |
| 61 | <tr> |
| 62 | <th>MDL Class</th> |
| 63 | <th>Effect</th> |
| 64 | <th>Remarks</th> |
| 65 | </tr> |
| 66 | </thead> |
| 67 | <tbody> |
| 68 | <tr> |
| 69 | <td><code>mdl-snackbar</code></td> |
| 70 | <td>Defines the container of the snackbar component.</td> |
| 71 | <td>Required on snackbar container</td> |
| 72 | </tr> |
| 73 | </tbody> |
| 74 | </table> |
| 75 | <h3 id="elements">Elements</h3> |
| 76 | <table> |
| 77 | <thead> |
| 78 | <tr> |
| 79 | <th>MDL Class</th> |
| 80 | <th>Effect</th> |
| 81 | <th>Remarks</th> |
| 82 | </tr> |
| 83 | </thead> |
| 84 | <tbody> |
| 85 | <tr> |
| 86 | <td><code>mdl-snackbar__text</code></td> |
| 87 | <td>Defines the element containing the text of the snackbar.</td> |
| 88 | <td>Required</td> |
| 89 | </tr> |
| 90 | <tr> |
| 91 | <td><code>mdl-snackbar__action</code></td> |
| 92 | <td>Defines the element that triggers the action of a snackbar.</td> |
| 93 | <td>Required</td> |
| 94 | </tr> |
| 95 | </tbody> |
| 96 | </table> |
| 97 | <h3 id="modifiers">Modifiers</h3> |
| 98 | <table> |
| 99 | <thead> |
| 100 | <tr> |
| 101 | <th>MDL Class</th> |
| 102 | <th>Effect</th> |
| 103 | <th>Remarks</th> |
| 104 | </tr> |
| 105 | </thead> |
| 106 | <tbody> |
| 107 | <tr> |
| 108 | <td><code>mdl-snackbar--active</code></td> |
| 109 | <td>Marks the snackbar as active which causes it to display.</td> |
| 110 | <td>Required when active. Controlled in JavaScript</td> |
| 111 | </tr> |
| 112 | </tbody> |
| 113 | </table> |
| 114 | <h2 id="data-object">Data Object</h2> |
| 115 | <p>The Snackbar components <code>showSnackbar</code> method takes an object for snackbar data. |
| 116 | The table below shows the properties and their usage.</p> |
| 117 | <table> |
| 118 | <thead> |
| 119 | <tr> |
| 120 | <th>Property</th> |
| 121 | <th>Effect</th> |
| 122 | <th>Remarks</th> |
| 123 | <th>Type</th> |
| 124 | </tr> |
| 125 | </thead> |
| 126 | <tbody> |
| 127 | <tr> |
| 128 | <td>message</td> |
| 129 | <td>The text message to display.</td> |
| 130 | <td>Required</td> |
| 131 | <td>String</td> |
| 132 | </tr> |
| 133 | <tr> |
| 134 | <td>timeout</td> |
| 135 | <td>The amount of time in milliseconds to show the snackbar.</td> |
| 136 | <td>Optional (default 2750)</td> |
| 137 | <td>Integer</td> |
| 138 | </tr> |
| 139 | <tr> |
| 140 | <td>actionHandler</td> |
| 141 | <td>The function to execute when the action is clicked.</td> |
| 142 | <td>Optional</td> |
| 143 | <td>Function</td> |
| 144 | </tr> |
| 145 | <tr> |
| 146 | <td>actionText</td> |
| 147 | <td>The text to display for the action button.</td> |
| 148 | <td>Required if actionHandler is set</td> |
| 149 | <td>String.</td> |
| 150 | </tr> |
| 151 | </tbody> |
| 152 | </table> |
| 153 | |
| 154 | |