Skip to content
This repository has been archived by the owner on Jan 13, 2025. It is now read-only.

Commit

Permalink
docs(snackbar): update format (#3375)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ALMaclaine
ALMaclaine authored and Kenneth G. Franqueiro committed Oct 30, 2018
1 parent 1e9289f commit 178bc9b
Showing 1 changed file with 90 additions and 147 deletions.
237 changes: 90 additions & 147 deletions packages/mdc-snackbar/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ Snackbars provide brief messages about app processes at the bottom of the screen
npm install @material/snackbar
```

## Usage
## Basic Usage

### Snackbar DOM
### HTML Structure

```html
<div class="mdc-snackbar"
Expand All @@ -51,106 +51,33 @@ npm install @material/snackbar
</div>
```

### Start Aligned Snackbars (tablet and desktop only)

MDC Snackbar can be start aligned (including in RTL contexts). To create a start-aligned
snackbar, add the `mdc-snackbar--align-start` modifier class to the root element.

```html
<div class="mdc-snackbar mdc-snackbar--align-start"
aria-live="assertive"
aria-atomic="true"
aria-hidden="true">
<div class="mdc-snackbar__text"></div>
<div class="mdc-snackbar__action-wrapper">
<button type="button" class="mdc-snackbar__action-button"></button>
</div>
</div>
```

### Using the JS Component

MDC Snackbar ships with a Component / Foundation combo which provides the API for showing snackbar
messages with optional action.

#### Including in code

##### ES2015

```javascript
import {MDCSnackbar, MDCSnackbarFoundation} from '@material/snackbar';
```

##### CommonJS
### Styles

```javascript
const mdcSnackbar = require('mdc-snackbar');
const MDCSnackbar = mdcSnackbar.MDCSnackbar;
const MDCSnackbarFoundation = mdcSnackbar.MDCSnackbarFoundation;
```scss
@import "@material/snackbar/mdc-snackbar";
```

##### AMD

```javascript
require(['path/to/mdc-snackbar'], mdcSnackbar => {
const MDCSnackbar = mdcSnackbar.MDCSnackbar;
const MDCSnackbarFoundation = mdcSnackbar.MDCSnackbarFoundation;
});
```

##### Global

```javascript
const MDCSnackbar = mdc.snackbar.MDCSnackbar;
const MDCSnackbarFoundation = mdc.snackbar.MDCSnackbarFoundation;
```
### JavaScript Instantiation

#### Automatic Instantiation
MDC Snackbar ships with a Component / Foundation combo which provides the API for showing snackbar messages with optional action.

If you do not care about retaining the component instance for the snackbar, simply call `attachTo()`
and pass it a DOM element.

```javascript
mdc.snackbar.MDCSnackbar.attachTo(document.querySelector('.mdc-snackbar'));
```

#### Manual Instantiation

Snackbars can easily be initialized using their default constructors as well, similar to `attachTo`.

```javascript
```js
import {MDCSnackbar} from '@material/snackbar';

const snackbar = new MDCSnackbar(document.querySelector('.mdc-snackbar'));
```

#### Handling events

When snackbar is shown or dismissed, the component will emit a `MDCSnackbar:show` or
`MDCSnackbar:hide` custom event with no data attached.
> See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript.
### Showing a message and action
## Variants

Once you have obtained an MDCSnackbar instance attached to the DOM, you can use
the `show` method to trigger the display of a message with optional action. The
`show` method takes an object for snackbar data. The table below shows the
properties and their usage.

| Property | Effect | Remarks | Type |
|-----------|--------|---------|---------|
| message | The text message to display. | Required | String |
| timeout | The amount of time in milliseconds to show the snackbar. | Optional (default 2750) | Integer |
| actionHandler | The function to execute when the action is clicked. | Optional | Function |
| actionText | The text to display for the action button. | Required if actionHandler is set | String |
| multiline | Whether to show the snackbar with space for multiple lines of text | Optional | Boolean |
| actionOnBottom | Whether to show the action below the multiple lines of text | Optional, applies when multiline is true | Boolean |

### Responding to a Snackbar Action
### Start Aligned Snackbars (tablet and desktop only)

To respond to a snackbar action, assign a function to the optional `actionHandler` property in the object that gets passed to the `show` method. If you choose to set this property, you *must _also_* set the `actionText` property.
MDC Snackbar can be start aligned (including in RTL contexts). To create a start-aligned
snackbar, add the `mdc-snackbar--align-start` modifier class to the root element.

```html
<div class="mdc-snackbar"
<div class="mdc-snackbar mdc-snackbar--align-start"
aria-live="assertive"
aria-atomic="true"
aria-hidden="true">
Expand All @@ -161,67 +88,9 @@ To respond to a snackbar action, assign a function to the optional `actionHandle
</div>
```

```js
import {MDCSnackbar} from '@material/snackbar';

const snackbar = new MDCSnackbar(document.querySelector('.mdc-snackbar'));
const dataObj = {
message: messageInput.value,
actionText: 'Undo',
actionHandler: function () {
console.log('my cool function');
}
};

snackbar.show(dataObj);
```


### Keep snackbar when the action button is pressed
### Additional Information

By default the snackbar will be dimissed when the user presses the action button.
If you want the snackbar to remain visible until the timeout is reached (regardless of
whether the user pressed the action button or not) you can set the `dismissesOnAction`
property to `false`:

```
const snackbar = new MDCSnackbar(document.querySelector('.mdc-snackbar'));
snackbar.dismissesOnAction = false
```

### Using the Foundation Class

MDC Snackbar ships with an `MDCSnackbarFoundation` class that external frameworks and libraries can
use to integrate the component. As with all foundation classes, an adapter object must be provided.
The adapter for snackbars must provide the following functions, with correct signatures:

| Method Signature | Description |
| --- | --- |
| `addClass(className: string) => void` | Adds a class to the root element. |
| `removeClass(className: string) => void` | Removes a class from the root element. |
| `setAriaHidden() => void` | Sets `aria-hidden="true"` on the root element. |
| `unsetAriaHidden() => void` | Removes the `aria-hidden` attribute from the root element. |
| `setActionAriaHidden() => void` | Sets `aria-hidden="true"` on the action element. |
| `unsetActionAriaHidden() => void` | Removes the `aria-hidden` attribute from the action element. |
| `setActionText(actionText: string) => void` | Set the text content of the action element. |
| `setMessageText(message: string) => void` | Set the text content of the message element. |
| `setFocus() => void` | Sets focus on the action button. |
| `isFocused() => boolean` | Detects focus on the action button. |
| `visibilityIsHidden() => boolean` | Returns document.hidden property. |
| `registerBlurHandler(handler: EventListener) => void` | Registers an event handler to be called when a `blur` event is triggered on the action button |
| `deregisterBlurHandler(handler: EventListener) => void` | Deregisters a `blur` event handler from the actionButton |
| `registerVisibilityChangeHandler(handler: EventListener) => void` | Registers an event handler to be called when a 'visibilitychange' event occurs |
| `deregisterVisibilityChangeHandler(handler: EventListener) => void` | Deregisters an event handler to be called when a 'visibilitychange' event occurs |
| `registerCapturedInteractionHandler(evtType: string, handler: EventListener) => void` | Registers an event handler to be called when the given event type is triggered on the `body` |
| `deregisterCapturedInteractionHandler(evtType: string, handler: EventListener) => void` | Deregisters an event handler from the `body` |
| `registerActionClickHandler(handler: EventListener) => void` | Registers an event handler to be called when a `click` event is triggered on the action element. |
| `deregisterActionClickHandler(handler: EventListener) => void` | Deregisters an event handler from a `click` event on the action element. This will only be called with handlers that have previously been passed to `registerActionClickHandler` calls. |
| `registerTransitionEndHandler(handler: EventListener) => void` | Registers an event handler to be called when an `transitionend` event is triggered on the root element. Note that you must account for vendor prefixes in order for this to work correctly. |
| `deregisterTransitionEndHandler(handler: EventListener) => void` | Deregisters an event handler from an `transitionend` event listener. This will only be called with handlers that have previously been passed to `registerTransitionEndHandler` calls. |
| `notifyShow() => void` | Dispatches an event notifying listeners that the snackbar has been shown. |
| `notifyHide() => void` | Dispatches an event notifying listeners that the snackbar has been hidden. |

## Avoiding Flash-Of-Unstyled-Content (FOUC)
#### Avoiding Flash-Of-Unstyled-Content (FOUC)

If you are loading the `mdc-snackbar` CSS asynchronously, you may experience a brief flash-of-unstyled-content (FOUC) due to the
snackbar's translate transition running once the CSS loads. To avoid this temporary FOUC, you can add the following simple style
Expand All @@ -231,3 +100,77 @@ before the `mdc-snackbar` CSS is loaded:
.mdc-snackbar { transform: translateY(100%); }
```
This will move the snackbar offscreen until the CSS is fully loaded and avoids a translate transition upon load.

## Style Customization

### CSS Classes

CSS Class | Description
--- | ---
`mdc-snackbar` | Mandatory. Container for the snackbar elements.
`mdc-snackbar__action-wrapper` | Mandatory. Wraps the action button.
`mdc-snackbar__action-button` | Mandatory. The action button.
`mdc-snackbar__text` | Mandtory. The next of the snackbar.
`mdc-snackbar--align-start` | Optional. Class to align snackbar to start, ltr dependent.
`mdc-snackbar--action-on-bottom` | Optional on the mdc-snackbar element. Moves action to bottom of snackbar. Can be applied in js.
`mdc-snackbar--multiline` | Optional on the mdc-snackbar element. Makes the snackbar multiple lines. Can be applied in js.

## `MDCSnackbar` Properties and Methods

Property | Value Type | Description
--- | --- | ---
`dismissesOnAction` | `boolean` | Whether the snackbar dismisses when the action is clicked, or if it waits for the timeout anyway. Defaults to `true`.

Method Signature | Description
--- | ---
`show(data: DataObject=) => void` | Displays the snackbar. `data` populates the snackbar and sets options (see below).

### DataObject Properties

Property | Type | Description
--- | --- | ---
`message` | string | Mandatory. The text message to display.
`timeout` | number | The amount of time in milliseconds to show the snackbar. Defaults to `2750`.
`actionHandler` | function | The function to execute when the action is clicked.
`actionText` | string | Mandatory if `actionHandler` is set. The text to display for the action button.
`multiline` | boolean | Whether to show the snackbar with space for multiple lines of text.
`actionOnBottom` | boolean | Whether to show the action below the multiple lines of text (only applicable when `multiline` is true).

### Events

Event Name | `event.detail` | Description
--- | --- | ---
`MDCSnackbar:hide` | `{}` | Emitted when the Snackbar is hidden.
`MDCSnackbar:show` | `{}` | Emitted when the Snackbar is shown.

## Usage Within Frameworks

If you are using a JavaScript framework, such as React or Angular, you can create a Snackbar for your framework. Depending on your needs, you can use the _Simple Approach: Wrapping MDC Web Vanilla Components_, or the _Advanced Approach: Using Foundations and Adapters_. Please follow the instructions [here](../../docs/integrating-into-frameworks.md).

### `MDCSnackbarAdapter`

Method Signature | Description
--- | ---
`addClass(className: string) => void` | Adds a class to the root element.
`removeClass(className: string) => void` | Removes a class from the root element.
`setAriaHidden() => void` | Sets `aria-hidden="true"` on the root element.
`unsetAriaHidden() => void` | Removes the `aria-hidden` attribute from the root element.
`setActionAriaHidden() => void` | Sets `aria-hidden="true"` on the action element.
`unsetActionAriaHidden() => void` | Removes the `aria-hidden` attribute from the action element.
`setActionText(actionText: string) => void` | Set the text content of the action element.
`setMessageText(message: string) => void` | Set the text content of the message element.
`setFocus() => void` | Sets focus on the action button.
`isFocused() => boolean` | Detects focus on the action button.
`visibilityIsHidden() => boolean` | Returns document.hidden property.
`registerBlurHandler(handler: EventListener) => void` | Registers an event handler to be called when a `blur` event is triggered on the action button.
`deregisterBlurHandler(handler: EventListener) => void` | Deregisters a `blur` event handler from the actionButton.
`registerVisibilityChangeHandler(handler: EventListener) => void` | Registers an event handler to be called when a 'visibilitychange' event occurs.
`deregisterVisibilityChangeHandler(handler: EventListener) => void` | Deregisters an event handler to be called when a 'visibilitychange' event occurs.
`registerCapturedInteractionHandler(evtType: string, handler: EventListener) => void` | Registers an event handler to be called when the given event type is triggered on the `body`.
`deregisterCapturedInteractionHandler(evtType: string, handler: EventListener) => void` | Deregisters an event handler from the `body`.
`registerActionClickHandler(handler: EventListener) => void` | Registers an event handler to be called when a `click` event is triggered on the action element.
`deregisterActionClickHandler(handler: EventListener) => void` | Deregisters an event handler from a `click` event on the action element. This will only be called with handlers that have previously been passed to `registerActionClickHandler` calls.
`registerTransitionEndHandler(handler: EventListener) => void` | Registers an event handler to be called when an `transitionend` event is triggered on the root element. Note that you must account for vendor prefixes in order for this to work correctly.
`deregisterTransitionEndHandler(handler: EventListener) => void` | Deregisters an event handler from an `transitionend` event listener. This will only be called with handlers that have previously been passed to `registerTransitionEndHandler` calls.
`notifyShow() => void` | Dispatches an event notifying listeners that the snackbar has been shown.
`notifyHide() => void` | Dispatches an event notifying listeners that the snackbar has been hidden.

0 comments on commit 178bc9b

Please sign in to comment.