diff --git a/edit-post/README.md b/edit-post/README.md index af78b310c4fd7..f03ae16000e0c 100644 --- a/edit-post/README.md +++ b/edit-post/README.md @@ -9,6 +9,88 @@ Refer to [the plugins module documentation](../plugins/) for more information. The following components can be used with the `registerPlugin` ([see documentation](../packages/plugins)) API. They can be found in the global variable `wp.editPost` when defining `wp-edit-post` as a script dependency. +### `PluginBlockSettingsMenuItem` + +Renders a new item in the block settings menu. + +Example: + +{% codetabs %} + +{% ES5 %} +```js +var __ = wp.i18n.__; +var PluginBlockSettingsMenuItem = wp.editPost.PluginBlockSettingsMenuItem; + +function doOnClick(){ + // To be called when the user clicks the menu item. +} + +function MyPluginBlockSettingsMenuItem() { + return el( + PluginBlockSettingsMenuItem, + { + allowedBlockNames: [ 'core/paragraph' ], + icon: 'dashicon-name', + label: __( 'Menu item text' ), + onClick: doOnClick, + } + ); +} +``` + +{% ESNext %} +```jsx +import { __ } from wp.i18n; +import { PluginBlockSettingsMenuItem } from wp.editPost; + +const doOnClick = ( ) => { + // To be called when the user clicks the menu item. +}; + +const MyPluginBlockSettingsMenuItem = () => ( + +); +``` + +{% end %} + +#### Props + +##### allowedBlockNames + +An array containing a whitelist of block names for which the item should be shown. If this prop is not present the item will be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. + +- Type: `Array` +- Required: No +- Default: Menu item is shown for any block + +##### icon + +The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. + +- Type: `String` | `Element` +- Required: No +- Default: Menu item wil be rendered without icon + +##### label + +A string containing the menu item text. + +- Type: `String` +- Required: Yes + +##### onClick + +The callback function to be executed when the user clicks the menu item. + +- Type: `function` +- Required: Yes + ### `PluginSidebar` Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar.