woocommerce/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/notices.md

291 lines
13 KiB
Markdown

# Frontend notices <!-- omit in toc -->
## Table of contents <!-- omit in toc -->
- [useStoreNotices()](#usestorenotices)
- [API](#api)
- [`addDefaultNotice( text = '', noticeProps = {} )`](#adddefaultnotice-text---noticeprops---)
- [`addErrorNotice( text = '', noticeProps = {} )`](#adderrornotice-text---noticeprops---)
- [`addWarningNotice( text = '', noticeProps = {} )`](#addwarningnotice-text---noticeprops---)
- [`addInfoNotice( text = '', noticeProps = {} )`](#addinfonotice-text---noticeprops---)
- [`addSuccessNotice( text = '', noticeProps = {} )`](#addsuccessnotice-text---noticeprops---)
- [`hasNoticesOfType( type )`](#hasnoticesoftype-type-)
- [`notices`](#notices)
- [`removeNotice( id, ctx )`](#removenotice-id-ctx-)
- [`removeNotices( status = null )`](#removenotices-status--null-)
- [`setIsSuppressed( val )`](#setissuppressed-val-)
- [StoreNoticesProvider](#storenoticesprovider)
- [Actions](#actions)
- [`createNotice( status = 'default', content = '', options = {} )`](#createnotice-status--default-content---options---)
- [`createSnackbarNotice( content = '', options = {} )`](#createsnackbarnotice-content---options---)
- [`removeNotice( id, ctx )`](#removenotice-id-ctx--1)
- [`setIsSuppressed( val )`](#setissuppressed-val--1)
- [Statuses](#statuses)
- [Notice options](#notice-options)
- [useStoreSnackbarNotices()](#usestoresnackbarnotices)
- [API](#api-1)
- [`addSnackbarNotice( text = '', noticeProps = {} )`](#addsnackbarnotice-text---noticeprops---)
- [`notices`](#notices-1)
- [`removeNotices( status = null )`](#removenotices-status--null--1)
- [StoreSnackbarNoticesProvider](#storesnackbarnoticesprovider)
- [Actions](#actions-1)
- [`createSnackbarNotice( content = '', options = {} )`](#createsnackbarnotice-content---options----1)
- [`removeSnackbarNotice( id, ctx )`](#removesnackbarnotice-id-ctx-)
- [`setIsSuppressed( val )`](#setissuppressed-val--2)
- [Example usage](#example-usage)
## useStoreNotices()
The `useStoreNotices()` hook allows reading and manipulating notices in the frontend.
### API
> _Note: if the context is not specified in `noticeProps` or `ctxt` params (depending on the method), the current context is used._
#### `addDefaultNotice( text = '', noticeProps = {} )`
Create a new notice with `default` status.
| Argument | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| `text` | string | Text to be displayed in the notice. |
| `noticeProps` | Object | Object with the [notice options](#notice-options). |
#### `addErrorNotice( text = '', noticeProps = {} )`
Create a new error notice.
| Argument | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| `text` | string | Text to be displayed in the notice. |
| `noticeProps` | Object | Object with the [notice options](#notice-options). |
#### `addWarningNotice( text = '', noticeProps = {} )`
Create a new warning notice.
| Argument | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| `text` | string | Text to be displayed in the notice. |
| `noticeProps` | Object | Object with the [notice options](#notice-options). |
#### `addInfoNotice( text = '', noticeProps = {} )`
Create a new info notice.
| Argument | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| `text` | string | Text to be displayed in the notice. |
| `noticeProps` | Object | Object with the [notice options](#notice-options). |
#### `addSuccessNotice( text = '', noticeProps = {} )`
Create a new success notice.
| Argument | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| `text` | string | Text to be displayed in the notice. |
| `noticeProps` | Object | Object with the [notice options](#notice-options). |
#### `hasNoticesOfType( type )`
Check whether there are notices of the provided type in the current context.
| Argument | Type | Description |
| -------- | ------ | ----------------------------- |
| `type` | string | Type of the notices to check. |
#### `notices`
An array of the notices in the current context.
#### `removeNotice( id, ctx )`
Remove an existing notice.
| Argument | Type | Description |
| -------- | ------ | --------------------------------------------- |
| `id` | string | Id of the notice to remove. |
| `ctx` | string | Context where the notice to remove is stored. |
#### `removeNotices( status = null )`
Remove all notices from the current context. If a `status` is provided, only the notices with that status are removed.
| Argument | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `status` | string | Status that notices must match to be removed. If not provided, all notices of any status are removed. |
#### `setIsSuppressed( val )`
Whether notices are suppressed. If true, it will hide the notices from the frontend.
| Argument | Type | Description |
| -------- | ------- | --------------------------- |
| `val` | boolean | Id of the notice to remove. |
## StoreNoticesProvider
The `StoreNoticesProvider` allows managing notices in the frontend. Notices are rendered before React Children.
Internally, it uses the `StoreNoticesContext` which relies on the [`notices` package](https://github.com/WordPress/gutenberg/tree/master/packages/notices) from Gutenberg.
### Actions
#### `createNotice( status = 'default', content = '', options = {} )`
This action creates a new notice. If the context is not specified in the `options` object, the current context is used.
| Argument | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| `status` | string | One of the statuses listed below. |
| `content` | string | Text to be displayed in the notice. |
| `options` | Object | Object with the [notice options](#notice-options). |
#### `createSnackbarNotice( content = '', options = {} )`
This action creates a new snackbar notice. If the context is not specified in the `options` object, the current context is used.
| Argument | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| `content` | string | Text to be displayed in the notice. |
| `options` | Object | Object with the [notice options](#notice-options). |
#### `removeNotice( id, ctx )`
This action removes an existing notice. If the context is not specified, the current context is used.
| Argument | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `id` | string | Id of the notice to remove. |
| `ctx` | string | Context where the notice to remove is stored. If the context is not specified, the current context is used. |
#### `setIsSuppressed( val )`
Whether notices are suppressed. If true, it will hide the notices from the frontend.
| Argument | Type | Description |
| -------- | ------- | --------------------------- |
| `val` | boolean | Id of the notice to remove. |
### Statuses
All notices must have one of the following statuses: `default`, `error`, `success`, `info`, `warning`.
### Notice options
Object of the form:
```js
{
id: 'checkout',
type: string,
isDismissible: false,
}
```
Refer to the [Gutenberg docs](https://github.com/WordPress/gutenberg/blob/master/packages/notices/src/store/actions.js#L46) to know the available options.
## useStoreSnackbarNotices()
The `useStoreNotices()` hook allows reading and manipulating snackbar notices in the frontend.
The snackbar is a small toast-like notification that appears at the bottom of a user's screen.
![Applied coupon code](https://user-images.githubusercontent.com/5656702/124294673-dd803b80-db4f-11eb-81ec-02fb962d04ed.png)
### API
#### `addSnackbarNotice( text = '', noticeProps = {} )`
Create a new snackbar notice.
| Argument | Type | Description |
| ------------- | ------ | -------------------------------------------------- |
| `text` | string | Text to be displayed in the notice. |
| `noticeProps` | Object | Object with the [notice options](#notice-options). |
#### `notices`
An array of the notices in the current context.
#### `removeNotices( status = null )`
Remove all notices from the current context. If a `status` is provided, only the notices with that status are removed.
| Argument | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `status` | string | Status that notices must match to be removed. If not provided, all notices of any status are removed. |
## StoreSnackbarNoticesProvider
The `StoreSnackbarNoticesProvider` allows managing snackbar notices in the frontend. Snackbar notices are displayed in the bottom left corner and disappear after a certain time.
Internally, it uses the `StoreNoticesContext` which relies on the [`notices` package](https://github.com/WordPress/gutenberg/tree/master/packages/notices) from Gutenberg.
### Actions
#### `createSnackbarNotice( content = '', options = {} )`
This action creates a new snackbar notice. If the context is not specified in the `options` object, the current context is used.
| Argument | Type | Description |
| --------- | ------ | -------------------------------------------------- |
| `content` | string | Text to be displayed in the notice. |
| `options` | Object | Object with the [notice options](#notice-options). |
#### `removeSnackbarNotice( id, ctx )`
This action removes an existing notice. If the context is not specified, the current context is used.
| Argument | Type | Description |
| -------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| `id` | string | Id of the notice to remove. |
| `ctx` | string | Context where the notice to remove is stored. If the context is not specified, the current context is used. |
#### `setIsSuppressed( val )`
Whether notices are suppressed. If true, it will hide the notices from the frontend.
| Argument | Type | Description |
| -------- | ------- | --------------------------- |
| `val` | boolean | Id of the notice to remove. |
## Example usage
The following example shows a `CheckoutProcessor` component that displays an error notice when the payment process fails and it removes it every time the payment is started. When the payment is completed correctly, it shows a snackbar notice.
```jsx
const CheckoutProcessor = () => {
const { addErrorNotice, removeNotice } = useStoreNotices();
// ...
const paymentFail = () => {
addErrorNotice( 'Something went wrong.', { id: 'checkout' } );
};
const paymentStart = () => {
removeNotice( 'checkout' );
};
// ...
};
```
```jsx
<StoreNoticesSnackbarProvider context="wc/checkout">
<StoreNoticesProvider context="wc/checkout">
// ...
<CheckoutProcessor />
</StoreNoticesProvider>
</StoreSnackbarNoticesProvider>
```
<!-- FEEDBACK -->
---
[We're hiring!](https://woocommerce.com/careers/) Come work with us!
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/internal-developers/block-client-apis/notices.md)
<!-- /FEEDBACK -->