diff --git a/docs/designers-developers/developers/tutorials/notices/README.md b/docs/designers-developers/developers/tutorials/notices/README.md new file mode 100644 index 00000000000000..63296f41dfb4db --- /dev/null +++ b/docs/designers-developers/developers/tutorials/notices/README.md @@ -0,0 +1,80 @@ +# Displaying Notices from Your Plugin or Theme + +Notices are informational UI displayed near the top of admin pages. WordPress core, themes, and plugins all use notices to indicate the result of an action, or to draw the user's attention to necessary information. + +In the Classic Editor, notices hooked onto the `admin_notices` action can render whatever HTML they'd like. In the Block Editor, notices are restricted to a more formal API. + +## Notices in the Classic Editor + +In the Classic Editor, here's an example of the "Post draft updated" notice: + +![Post draft updated in the Classic Editor](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png) + +Producing an equivalent "Post draft updated" notice would require code like this: + +```php +/** + * Hook into the 'admin_notices' action to render + * a generic HTML notice. + */ +function myguten_admin_notice() { + $screen = get_current_screen(); + // Only render this notice in the post editor. + if ( ! $screen || 'post' !== $screen->base ) { + return; + } + // Render the notice's HTML. + // Each notice should be wrapped in a
+ // with a 'notice' class. + echo '

'; + echo sprintf( __( 'Post draft updated. Preview post' ), get_preview_post_link() ); + echo '

'; +}; +add_action( 'admin_notices', 'myguten_admin_notice' ); +``` + +Importantly, the `admin_notices` hook allows a developer to render whatever HTML they'd like. One advantage is that the developer has a great amount of flexibility. The key disadvantage is that arbitrary HTML makes future iterations on notices more difficult, if not possible, because the iterations need to accommodate for arbitrary HTML. This is why the Block Editor has a formal API. + +## Notices in the Block Editor + +In the Block Editor, here's an example of the "Post published" notice: + +![Post published in the Block Editor](https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/notices/block-editor-notice.png) + +Producing an equivalent "Post published" notice would require code like this: + +```js +( function( wp ) { + wp.data.dispatch('core/notices').createNotice( + 'success', // Can be one of: success, info, warning, error. + 'Post published.', // Text string to display. + { + isDismissible: true, // Whether the user can dismiss the notice. + // Any actions the user can perform. + actions: [ + { + url: '#', + label: 'View post' + } + ] + } + ); +} )( window.wp ); +``` + +You'll want to use this _Notices Data API_ when producing a notice from within the JavaScript application lifecycle. + +To better understand the specific code example above: + +* `wp` is WordPress global window variable. +* `wp.data` is an object provided by the Block Editor for accessing the Block Editor data store. +* `wp.data.dispatch('core/notices')` accesses functionality registered to the Block Editor data store by the Notices package. +* `createNotice()` is a function offered by the Notices package to register a new notice. The Block Editor reads from the notice data store in order to know which notices to display. + +Check out the [_Loading JavaScript_](/docs/designers-developers/developers/tutorials/javascript/loading-javascript.md) tutorial for a primer on how to load your custom JavaScript into the Block Editor. + +## Learn More + +The Block Editor offers a complete API for generating notices. The official documentation is a great place to review what's possible. + +For a full list of the available actions and selectors, refer to the [Notices Data Handbook](/docs/designers-developers/developers/data/data-core-notices.md) page. diff --git a/docs/designers-developers/developers/tutorials/notices/block-editor-notice.png b/docs/designers-developers/developers/tutorials/notices/block-editor-notice.png new file mode 100644 index 00000000000000..89bf3e48c0c596 Binary files /dev/null and b/docs/designers-developers/developers/tutorials/notices/block-editor-notice.png differ diff --git a/docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png b/docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png new file mode 100644 index 00000000000000..d96f4aa79a2e45 Binary files /dev/null and b/docs/designers-developers/developers/tutorials/notices/classic-editor-notice.png differ diff --git a/docs/designers-developers/developers/tutorials/readme.md b/docs/designers-developers/developers/tutorials/readme.md index f63254cd3fbb59..dd063e13e5d644 100644 --- a/docs/designers-developers/developers/tutorials/readme.md +++ b/docs/designers-developers/developers/tutorials/readme.md @@ -6,6 +6,8 @@ * See the [Meta Boxes Tutorial](/docs/designers-developers/developers/tutorials/metabox/readme.md) for new ways of extending the editor storing and using post meta data. +* Check out the [Notices Tutorial](/docs/designers-developers/developers/tutorials/notices/README.md) to learn how to display informational UI at the top of the editor. + * The [Sidebar Tutorial](/docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md) will walk you through the steps of creating a sidebar to update data from the `post_meta` table. * Learn how to add customized buttons to the toolbar with the [Format API tutorial](/docs/designers-developers/developers/tutorials/format-api/). diff --git a/docs/manifest.json b/docs/manifest.json index 6e6dbd2e40251c..974392def6be0c 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -281,6 +281,12 @@ "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md", "parent": "metabox" }, + { + "title": "Displaying Notices from Your Plugin or Theme", + "slug": "notices", + "markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/notices/README.md", + "parent": "tutorials" + }, { "title": "Creating a sidebar for your plugin", "slug": "plugin-sidebar-0", diff --git a/docs/toc.json b/docs/toc.json index 14bed66d0a75e7..10baee15523065 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -53,6 +53,7 @@ {"docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md": []}, {"docs/designers-developers/developers/tutorials/metabox/meta-block-5-finishing.md": []} ]}, + {"docs/designers-developers/developers/tutorials/notices/README.md": []}, {"docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-0.md": [ {"docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-1-up-and-running.md": []}, {"docs/designers-developers/developers/tutorials/sidebar-tutorial/plugin-sidebar-2-styles-and-controls.md": []},