[Documentation] Add examples for all actions/selectors for the @wordp…

…ress/notice package. (#42077) * Add npmDevDependencies as a template variable. Update messaging to show what packages are being installed. * Remove extra code block added in error. * Add examples for createNotice and createSuccessNotice. * Add createInfoNotice example. * Adding examples for createErrorNotice, createInfoNotice, createSuccessNotice and createWarningNotice. * Adds example for removeNotice. * Clean up code examples. * Updates per code review. * Changes store references to noticesStore.
WordPress · Jul 6, 2022 · af7da80 · af7da80
1 parent 1339b96
commit af7da80
Show file tree

Hide file tree

Showing 3 changed files with 324 additions and 9 deletions.
diff --git a/docs/reference-guides/data/data-core-notices.md b/docs/reference-guides/data/data-core-notices.md
@@ -14,11 +14,12 @@ the global context.
 _Usage_
 
 ```js
-// This example retrieves all notices and displays their messages in a unordered list.
+import { useSelect } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
 
 const ExampleComponent = () => {
 	const notices = useSelect( ( select ) =>
-		select( 'core/notices' ).getNotices()
+		select( noticesStore ).getNotices()
 	);
 	return (
 		<ul>
@@ -54,6 +55,33 @@ _Related_
 
 -   createNotice
 
+_Usage_
+
+```js
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
+import { Button } from '@wordpress/components';
+
+const ExampleComponent = () => {
+	const { createErrorNotice } = useDispatch( noticesStore );
+	return (
+		<Button
+			onClick={ () =>
+				createErrorNotice( __( 'An error occurred!' ), {
+					type: 'snackbar',
+					explicitDismiss: true,
+				} )
+			}
+		>
+			{ __(
+				'Generate an snackbar error notice with explicit dismiss button.'
+			) }
+		</Button>
+	);
+};
+```
+
 _Parameters_
 
 -   _content_ `string`: Notice message.
@@ -72,6 +100,30 @@ _Related_
 
 -   createNotice
 
+_Usage_
+
+```js
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
+import { Button } from '@wordpress/components';
+
+const ExampleComponent = () => {
+	const { createInfoNotice } = useDispatch( noticesStore );
+	return (
+		<Button
+			onClick={ () =>
+				createInfoNotice( __( 'Something happened!' ), {
+					isDismissible: false,
+				} )
+			}
+		>
+			{ __( 'Generate a notice that cannot be dismissed.' ) }
+		</Button>
+	);
+};
+```
+
 _Parameters_
 
 -   _content_ `string`: Notice message.
@@ -85,6 +137,26 @@ _Returns_
 
 Returns an action object used in signalling that a notice is to be created.
 
+_Usage_
+
+```js
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
+import { Button } from '@wordpress/components';
+
+const ExampleComponent = () => {
+	const { createNotice } = useDispatch( noticesStore );
+	return (
+		<Button
+			onClick={ () => createNotice( 'success', __( 'Notice message' ) ) }
+		>
+			{ __( 'Generate a success notice!' ) }
+		</Button>
+	);
+};
+```
+
 _Parameters_
 
 -   _status_ `[string]`: Notice status.
@@ -96,8 +168,8 @@ _Parameters_
 -   _options.type_ `[string]`: Type of notice, one of `default`, or `snackbar`.
 -   _options.speak_ `[boolean]`: Whether the notice content should be announced to screen readers.
 -   _options.actions_ `[Array<WPNoticeAction>]`: User actions to be presented with notice.
--   _options.icon_ `[Object]`: An icon displayed with the notice.
--   _options.explicitDismiss_ `[boolean]`: Whether the notice includes an explict dismiss button and can't be dismissed by clicking the body of the notice.
+-   _options.icon_ `[string]`: An icon displayed with the notice. Only used when type is set to `snackbar`.
+-   _options.explicitDismiss_ `[boolean]`: Whether the notice includes an explicit dismiss button and can't be dismissed by clicking the body of the notice. Only applies when type is set to `snackbar`.
 -   _options.onDismiss_ `[Function]`: Called when the notice is dismissed.
 
 _Returns_
@@ -113,6 +185,31 @@ _Related_
 
 -   createNotice
 
+_Usage_
+
+```js
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
+import { Button } from '@wordpress/components';
+
+const ExampleComponent = () => {
+	const { createSuccessNotice } = useDispatch( noticesStore );
+	return (
+		<Button
+			onClick={ () =>
+				createSuccessNotice( __( 'Success!' ), {
+					type: 'snackbar',
+					icon: '🔥',
+				} )
+			}
+		>
+			{ __( 'Generate a snackbar success notice!' ) }
+		</Button>
+	);
+};
+```
+
 _Parameters_
 
 -   _content_ `string`: Notice message.
@@ -131,6 +228,35 @@ _Related_
 
 -   createNotice
 
+_Usage_
+
+```js
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
+import { Button } from '@wordpress/components';
+
+const ExampleComponent = () => {
+	const { createWarningNotice, createInfoNotice } =
+		useDispatch( noticesStore );
+	return (
+		<Button
+			onClick={ () =>
+				createWarningNotice( __( 'Warning!' ), {
+					onDismiss: () => {
+						createInfoNotice(
+							__( 'The warning has been dismissed!' )
+						);
+					},
+				} )
+			}
+		>
+			{ __( 'Generates a warning notice with onDismiss callback' ) }
+		</Button>
+	);
+};
+```
+
 _Parameters_
 
 -   _content_ `string`: Notice message.
@@ -144,6 +270,41 @@ _Returns_
 
 Returns an action object used in signalling that a notice is to be removed.
 
+_Usage_
+
+```js
+import { __ } from '@wordpress/i18n';
+import { useDispatch } from '@wordpress/data';
+import { store as noticesStore } from '@wordpress/notices';
+import { Button } from '@wordpress/components';
+
+const ExampleComponent = () => {
+	const notices = useSelect( ( select ) =>
+		select( noticesStore ).getNotices()
+	);
+	const { createWarningNotice, removeNotice } = useDispatch( noticesStore );
+
+	return (
+		<>
+			<Button
+				onClick={ () =>
+					createWarningNotice( __( 'Warning!' ), {
+						isDismissible: false,
+					} )
+				}
+			>
+				{ __( 'Generate a notice' ) }
+			</Button>
+			{ notices.length > 0 && (
+				<Button onClick={ () => removeNotice( notices[ 0 ].id ) }>
+					{ __( 'Remove the notice' ) }
+				</Button>
+			) }
+		</>
+	);
+};
+```
+
 _Parameters_
 
 -   _id_ `string`: Notice unique identifier.