diff --git a/bin/update-readmes.js b/bin/update-readmes.js index f15bedfdd0b64..b649ef5f99603 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -19,7 +19,7 @@ const packages = [ 'dom', 'dom-ready', 'e2e-test-utils', - //'edit-post', + 'edit-post', 'element', 'escape-html', 'html-entities', diff --git a/packages/edit-post/README.md b/packages/edit-post/README.md index ca4fc9e947dd2..0c8eb1326e884 100644 --- a/packages/edit-post/README.md +++ b/packages/edit-post/README.md @@ -20,21 +20,40 @@ Extending the editor UI can be accomplished with the `registerPlugin` API, allow Refer to [the plugins module documentation](/packages/plugins/README.md) for more information. -## Plugin Components - -The following components can be used with the `registerPlugin` ([see documentation](/packages/plugins/README.md)) API. +The components exported through the API can be used with the `registerPlugin` ([see documentation](/packages/plugins/README.md)) API. They can be found in the global variable `wp.editPost` when defining `wp-edit-post` as a script dependency. -### `PluginBlockSettingsMenuItem` +## API -Renders a new item in the block settings menu. + + +### initializeEditor + +[src/index.js#L66-L96](src/index.js#L66-L96) + +Initializes and returns an instance of Editor. + +The return value of this function is not necessary if we change where we +call initializeEditor(). This is due to metaBox timing. + +**Parameters** -Example: +- **id** `string`: Unique identifier for editor instance. +- **postType** `Object`: Post type of the post to edit. +- **postId** `Object`: ID of the post to edit. +- **settings** `?Object`: Editor settings object. +- **initialEdits** `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt). -{% codetabs %} +### PluginBlockSettingsMenuItem + +[src/index.js#L98-L98](src/index.js#L98-L98) + +Renders a new item in the block settings menu. + +**Usage** -{% ES5 %} ```js +// Using ES5 syntax var __ = wp.i18n.__; var PluginBlockSettingsMenuItem = wp.editPost.PluginBlockSettingsMenuItem; @@ -55,8 +74,8 @@ function MyPluginBlockSettingsMenuItem() { } ``` -{% ESNext %} ```jsx +// Using ESNext syntax import { __ } from wp.i18n; import { PluginBlockSettingsMenuItem } from wp.editPost; @@ -73,149 +92,29 @@ 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. - -If you wish to display the sidebar, you can with use the [`PluginSidebarMoreMenuItem`](#pluginsidebarmoremenuitem) component or the `wp.data.dispatch` API: - -```js -wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/sidebar-name' ); -``` - -_Example:_ - -{% codetabs %} - -{% ES5 %} -```js -var __ = wp.i18n.__; -var el = wp.element.createElement; -var PanelBody = wp.components.PanelBody; -var PluginSidebar = wp.editPost.PluginSidebar; - - -function MyPluginSidebar() { - return el( - PluginSidebar, - { - name: 'my-sidebar', - title: 'My sidebar title', - icon: 'smiley', - }, - el( - PanelBody, - {}, - __( 'My sidebar content' ) - ) - ); -} -``` - -{% ESNext %} -```jsx -const { __ } = wp.i18n; -const { PanelBody } = wp.components; -const { PluginSidebar } = wp.editPost; - -const MyPluginSidebar = () => ( - - - { __( 'My sidebar content' ) } - - -); -``` -{% end %} - -#### Props - -##### name - -A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. - -- Type: `String` -- Required: Yes +**Parameters** -##### className +- **props** `Object`: Component props. +- **props.allowedBlockNames** `[Array]`: An array containing a list of block names for which the item should be shown. If not present, it'll 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. +- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. +- **props.label** `string`: The menu item text. +- **props.onClick** `Function`: Callback function to be executed when the user click the menu item. -An optional class name added to the sidebar body. +**Returns** -- Type: `String` -- Required: No +`WPElement`: The WPElement to be rendered. -##### title +### PluginMoreMenuItem -Title displayed at the top of the sidebar. - -- Type: `String` -- Required: Yes - -##### isPinnable - -Whether to allow to pin sidebar to toolbar. - -- Type: `Boolean` -- Required: No -- Default: `true` - -##### icon - -The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. - -- Type: `String` | `Element` -- Required: No -- Default: _inherits from the plugin_ - -### `PluginMoreMenuItem` +[src/index.js#L99-L99](src/index.js#L99-L99) Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to as a button or link depending on the props provided. The text within the component appears as the menu item label. -_Example:_ - -{% codetabs %} +**Usage** -{% ES5 %} ```js +// Using ES5 syntax var __ = wp.i18n.__; var PluginMoreMenuItem = wp.editPost.PluginMoreMenuItem; @@ -235,8 +134,8 @@ function MyButtonMoreMenuItem() { } ``` -{% ESNext %} ```jsx +// Using ESNext syntax const { __ } = wp.i18n; const { PluginMoreMenuItem } = wp.editPost; @@ -253,106 +152,85 @@ const MyButtonMoreMenuItem = () => ( ); ``` -{% end %} - -#### Props - -`PluginMoreMenuItem` supports the following props. Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. - -##### href - -When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. -- Type: `String` -- Required: No +**Parameters** -##### icon +- **props** `Object`: Component properties. +- **props.href** `[string]`: When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. +- **props.icon** `[(string|Element)]`: 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. +- **props.onClick** `[Function]`: The callback function to be executed when the user clicks the menu item. +- **props.other** `[...*]`: Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. -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. +**Returns** -- Type: `String` | `Element` -- Required: No -- Default: _inherits from the plugin_ +`WPElement`: The element to be rendered. -##### onClick +### PluginPostPublishPanel -The callback function to be executed when the user clicks the menu item. +[src/index.js#L100-L100](src/index.js#L100-L100) -- Type: `function` -- Required: No -- Default: _function which does nothing_ +Renders provided content to the post-publish panel in the publish flow +(side panel that opens after a user publishes the post). -### `PluginSidebarMoreMenuItem` +**Usage** -Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to activate the corresponding `PluginSidebar` component. -The text within the component appears as the menu item label. - -_Example:_ - -{% codetabs %} - -{% ES5 %} ```js +// Using ES5 syntax var __ = wp.i18n.__; -var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem; +var PluginPostPublishPanel = wp.editPost.PluginPostPublishPanel; -function MySidebarMoreMenuItem() { +function MyPluginPostPublishPanel() { return wp.element.createElement( - PluginSidebarMoreMenuItem, + PluginPostPublishPanel, { - target: 'my-sidebar', - icon: 'smiley', + className: 'my-plugin-post-publish-panel', + title: __( 'My panel title' ), + initialOpen: true, }, - __( 'My sidebar title' ) - ) + __( 'My panel content' ) + ); } ``` -{% ESNext %} ```jsx +// Using ESNext syntax const { __ } = wp.i18n; -const { PluginSidebarMoreMenuItem } = wp.editPost; +const { PluginPostPublishPanel } = wp.editPost; -const MySidebarMoreMenuItem = () => ( - ( + - { __( 'My sidebar title' ) } - + { __( 'My panel content' ) } + ); ``` -{% end %} -#### Props +**Parameters** -##### target +- **props** `Object`: Component properties. +- **props.className** `[string]`: An optional class name added to the panel. +- **props.title** `[string]`: Title displayed at the top of the panel. +- **props.initialOpen** `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. +**Returns** -- Type: `String` -- Required: Yes +`WPElement`: The WPElement to be rendered. -##### icon +### PluginPostStatusInfo -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: _inherits from the plugin_ - - -### `PluginPostStatusInfo` +[src/index.js#L101-L101](src/index.js#L101-L101) Renders a row in the Status & Visibility panel of the Document sidebar. -It should be noted that this is named and implemented around the function it serves and not its location, which may change in future iterations. +It should be noted that this is named and implemented around the function it serves +and not its location, which may change in future iterations. -_Example:_ +**Usage** -{% codetabs %} - -{% ES5 %} ```js +// Using ES5 syntax var __ = wp.i18n.__; var PluginPostStatusInfo = wp.editPost.PluginPostStatusInfo; @@ -367,8 +245,8 @@ function MyPluginPostStatusInfo() { } ``` -{% ESNext %} ```jsx +// Using ESNext syntax const { __ } = wp.i18n; const { PluginPostStatusInfo } = wp.editPost; @@ -380,27 +258,27 @@ const MyPluginPostStatusInfo = () => ( ); ``` -{% end %} -#### Props +**Parameters** -##### className +- **props** `Object`: Component properties. +- **props.className** `[string]`: An optional class name added to the row. -An optional class name added to the row. +**Returns** -- Type: `String` -- Required: No +`WPElement`: The WPElement to be rendered. -### `PluginPrePublishPanel` +### PluginPrePublishPanel -Renders provided content to the pre-publish side panel in the publish flow (side panel that opens when a user first pushes "Publish" from the main editor). +[src/index.js#L102-L102](src/index.js#L102-L102) -_Example:_ +Renders provided content to the pre-publish side panel in the publish flow +(side panel that opens when a user first pushes "Publish" from the main editor). -{% codetabs %} +**Usage** -{% ES5 %} ```js +// Using ES5 syntax var __ = wp.i18n.__; var PluginPrePublishPanel = wp.editPost.PluginPrePublishPanel; @@ -417,8 +295,8 @@ function MyPluginPrePublishPanel() { } ``` -{% ESNext %} ```jsx +// Using ESNext syntax const { __ } = wp.i18n; const { PluginPrePublishPanel } = wp.editPost; @@ -432,99 +310,160 @@ const MyPluginPrePublishPanel = () => ( ); ``` -{% end %} -#### Props +**Parameters** -##### className +- **props** `Object`: Component props. +- **props.className** `[string]`: An optional class name added to the panel. +- **props.title** `[string]`: Title displayed at the top of the panel. +- **props.initialOpen** `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -An optional class name added to the panel. +**Returns** -- Type: `String` -- Required: No +`WPElement`: The WPElement to be rendered. -##### title +### PluginSidebar -Title displayed at the top of the panel. +[src/index.js#L103-L103](src/index.js#L103-L103) -- Type: `String` -- Required: No +Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar. +If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API: -##### initialOpen +```js +wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/sidebar-name' ); +``` -Whether to have the panel initially opened. When no title is provided it is always opened. +**Related** -- Type: `Boolean` -- Required: No -- Default: `false` +- PluginSidebarMoreMenuItem +**Usage** -### `PluginPostPublishPanel` +```js +// Using ES5 syntax +var __ = wp.i18n.__; +var el = wp.element.createElement; +var PanelBody = wp.components.PanelBody; +var PluginSidebar = wp.editPost.PluginSidebar; -Renders provided content to the post-publish panel in the publish flow (side panel that opens after a user publishes the post). +function MyPluginSidebar() { + return el( + PluginSidebar, + { + name: 'my-sidebar', + title: 'My sidebar title', + icon: 'smiley', + }, + el( + PanelBody, + {}, + __( 'My sidebar content' ) + ) + ); +} +``` -_Example:_ +```jsx +// Using ESNext syntax +const { __ } = wp.i18n; +const { PanelBody } = wp.components; +const { PluginSidebar } = wp.editPost; + +const MyPluginSidebar = () => ( + + + { __( 'My sidebar content' ) } + + +); +``` + +**Parameters** + +- **props** `Object`: Element props. +- **props.name** `string`: A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin. +- **props.className** `[string]`: An optional class name added to the sidebar body. +- **props.title** `string`: Title displayed at the top of the sidebar. +- **props.isPinnable** `[boolean]`: Whether to allow to pin sidebar to toolbar. +- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + +**Returns** -{% codetabs %} +`WPElement`: Plugin sidebar component. + +### PluginSidebarMoreMenuItem + +[src/index.js#L104-L104](src/index.js#L104-L104) + +Renders a menu item in `Plugins` group in `More Menu` drop down, +and can be used to activate the corresponding `PluginSidebar` component. +The text within the component appears as the menu item label. + +**Usage** -{% ES5 %} ```js +// Using ES5 syntax var __ = wp.i18n.__; -var PluginPostPublishPanel = wp.editPost.PluginPostPublishPanel; +var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem; -function MyPluginPostPublishPanel() { +function MySidebarMoreMenuItem() { return wp.element.createElement( - PluginPostPublishPanel, + PluginSidebarMoreMenuItem, { - className: 'my-plugin-post-publish-panel', - title: __( 'My panel title' ), - initialOpen: true, + target: 'my-sidebar', + icon: 'smiley', }, - __( 'My panel content' ) - ); + __( 'My sidebar title' ) + ) } ``` -{% ESNext %} ```jsx +// Using ESNext syntax const { __ } = wp.i18n; -const { PluginPostPublishPanel } = wp.editPost; +const { PluginSidebarMoreMenuItem } = wp.editPost; -const MyPluginPostPublishPanel = () => ( - ( + - { __( 'My panel content' ) } - + { __( 'My sidebar title' ) } + ); ``` -{% end %} -#### Props +**Parameters** -##### className +- **props** `Object`: Component props. +- **props.target** `string`: A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. +- **props.icon** `[(string|Element)]`: 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. -An optional class name added to the panel. +**Returns** -- Type: `String` -- Required: No +`WPElement`: The element to be rendered. -##### title +### reinitializeEditor -Title displayed at the top of the panel. +[src/index.js#L35-L50](src/index.js#L35-L50) -- Type: `String` -- Required: No +Reinitializes the editor after the user chooses to reboot the editor after +an unhandled error occurs, replacing previously mounted editor element using +an initial state from prior to the crash. -##### initialOpen +**Parameters** -Whether to have the panel initially opened. When no title is provided it is always opened. +- **postType** `Object`: Post type of the post to edit. +- **postId** `Object`: ID of the post to edit. +- **target** `Element`: DOM node in which editor is rendered. +- **settings** `?Object`: Editor settings object. +- **initialEdits** `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt). -- Type: `Boolean` -- Required: No -- Default: `false` +

Code is Poetry.

diff --git a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js index f887931acc8f7..810d558346cc7 100644 --- a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js +++ b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js @@ -30,6 +30,59 @@ const isEverySelectedBlockAllowed = ( selected, allowed ) => difference( selecte const shouldRenderItem = ( selectedBlockNames, allowedBlockNames ) => ! Array.isArray( allowedBlockNames ) || isEverySelectedBlockAllowed( selectedBlockNames, allowedBlockNames ); +/** + * Renders a new item in the block settings menu. + * + * @param {Object} props Component props. + * @param {Array} [props.allowedBlockNames] An array containing a list of block names for which the item should be shown. If not present, it'll 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. + * @param {string|Element} [props.icon] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. + * @param {string} props.label The menu item text. + * @param {Function} props.onClick Callback function to be executed when the user click the menu item. + * + * @example ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var PluginBlockSettingsMenuItem = wp.editPost.PluginBlockSettingsMenuItem; + * + * function doOnClick(){ + * // To be called when the user clicks the menu item. + * } + * + * function MyPluginBlockSettingsMenuItem() { + * return wp.element.createElement( + * PluginBlockSettingsMenuItem, + * { + * allowedBlockNames: [ 'core/paragraph' ], + * icon: 'dashicon-name', + * label: __( 'Menu item text' ), + * onClick: doOnClick, + * } + * ); + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * import { __ } from wp.i18n; + * import { PluginBlockSettingsMenuItem } from wp.editPost; + * + * const doOnClick = ( ) => { + * // To be called when the user clicks the menu item. + * }; + * + * const MyPluginBlockSettingsMenuItem = () => ( + * + * ); + * ``` + * + * @return {WPElement} The WPElement to be rendered. + */ const PluginBlockSettingsMenuItem = ( { allowedBlocks, icon, label, onClick, small, role } ) => ( { ( { selectedBlocks, onClose } ) => { diff --git a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js index 2f2e279c7616a..e29ec22e90a20 100644 --- a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js @@ -26,6 +26,60 @@ const PluginMoreMenuItem = ( { onClick = noop, ...props } ) => ( ); +/** + * Renders a menu item in `Plugins` group in `More Menu` drop down, and can be used to as a button or link depending on the props provided. + * The text within the component appears as the menu item label. + * + * @param {Object} props Component properties. + * @param {string} [props.href] When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. + * @param {string|Element} [props.icon=inherits from the plugin] 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. + * @param {Function} [props.onClick=noop] The callback function to be executed when the user clicks the menu item. + * @param {...*} [props.other] Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. + * + * @example ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var PluginMoreMenuItem = wp.editPost.PluginMoreMenuItem; + * + * function onButtonClick() { + * alert( 'Button clicked.' ); + * } + * + * function MyButtonMoreMenuItem() { + * return wp.element.createElement( + * PluginMoreMenuItem, + * { + * icon: 'smiley', + * onClick: onButtonClick + * }, + * __( 'My button title' ) + * ) + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * const { __ } = wp.i18n; + * const { PluginMoreMenuItem } = wp.editPost; + * + * function onButtonClick() { + * alert( 'Button clicked.' ); + * } + * + * const MyButtonMoreMenuItem = () => ( + * + * { __( 'My button title' ) } + * + * ); + * ``` + * + * @return {WPElement} The element to be rendered. + */ export default compose( withPluginContext( ( context, ownProps ) => { return { diff --git a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js index 0579ccec8a3b0..e1849f2e7890e 100644 --- a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js @@ -21,6 +21,51 @@ const PluginSidebarMoreMenuItem = ( { children, icon, isSelected, onClick } ) => ); +/** + * Renders a menu item in `Plugins` group in `More Menu` drop down, + * and can be used to activate the corresponding `PluginSidebar` component. + * The text within the component appears as the menu item label. + * + * @param {Object} props Component props. + * @param {string} props.target A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. + * @param {string|Element} [props.icon=inherits from the plugin] 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. + * + * @example ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem; + * + * function MySidebarMoreMenuItem() { + * return wp.element.createElement( + * PluginSidebarMoreMenuItem, + * { + * target: 'my-sidebar', + * icon: 'smiley', + * }, + * __( 'My sidebar title' ) + * ) + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * const { __ } = wp.i18n; + * const { PluginSidebarMoreMenuItem } = wp.editPost; + * + * const MySidebarMoreMenuItem = () => ( + * + * { __( 'My sidebar title' ) } + * + * ); + * ``` + * + * @return {WPElement} The element to be rendered. + */ export default compose( withPluginContext( ( context, ownProps ) => { return { diff --git a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js index a23dd1a9a2ff6..b8a49115e5d54 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js @@ -5,6 +5,53 @@ import { createSlotFill, PanelBody } from '@wordpress/components'; const { Fill, Slot } = createSlotFill( 'PluginPostPublishPanel' ); +/** + * Renders provided content to the post-publish panel in the publish flow + * (side panel that opens after a user publishes the post). + * + * @param {Object} props Component properties. + * @param {string} [props.className] An optional class name added to the panel. + * @param {string} [props.title] Title displayed at the top of the panel. + * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. + * + * @example ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var PluginPostPublishPanel = wp.editPost.PluginPostPublishPanel; + * + * function MyPluginPostPublishPanel() { + * return wp.element.createElement( + * PluginPostPublishPanel, + * { + * className: 'my-plugin-post-publish-panel', + * title: __( 'My panel title' ), + * initialOpen: true, + * }, + * __( 'My panel content' ) + * ); + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * const { __ } = wp.i18n; + * const { PluginPostPublishPanel } = wp.editPost; + * + * const MyPluginPostPublishPanel = () => ( + * + * { __( 'My panel content' ) } + * + * ); + * ``` + * + * @return {WPElement} The WPElement to be rendered. + */ const PluginPostPublishPanel = ( { children, className, title, initialOpen = false } ) => ( ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var PluginPostStatusInfo = wp.editPost.PluginPostStatusInfo; + * + * function MyPluginPostStatusInfo() { + * return wp.element.createElement( + * PluginPostStatusInfo, + * { + * className: 'my-plugin-post-status-info', + * }, + * __( 'My post status info' ) + * ) + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * const { __ } = wp.i18n; + * const { PluginPostStatusInfo } = wp.editPost; + * + * const MyPluginPostStatusInfo = () => ( + * + * { __( 'My post status info' ) } + * + * ); + * ``` + * + * @return {WPElement} The WPElement to be rendered. + */ const PluginPostStatusInfo = ( { children, className } ) => ( diff --git a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js index 6803b039e2628..7ffe80fb6e6a4 100644 --- a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js @@ -5,6 +5,53 @@ import { createSlotFill, PanelBody } from '@wordpress/components'; const { Fill, Slot } = createSlotFill( 'PluginPrePublishPanel' ); +/** + * Renders provided content to the pre-publish side panel in the publish flow + * (side panel that opens when a user first pushes "Publish" from the main editor). + * + * @param {Object} props Component props. + * @param {string} [props.className] An optional class name added to the panel. + * @param {string} [props.title] Title displayed at the top of the panel. + * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. + * + * @example ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var PluginPrePublishPanel = wp.editPost.PluginPrePublishPanel; + * + * function MyPluginPrePublishPanel() { + * return wp.element.createElement( + * PluginPrePublishPanel, + * { + * className: 'my-plugin-pre-publish-panel', + * title: __( 'My panel title' ), + * initialOpen: true, + * }, + * __( 'My panel content' ) + * ); + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * const { __ } = wp.i18n; + * const { PluginPrePublishPanel } = wp.editPost; + * + * const MyPluginPrePublishPanel = () => ( + * + * { __( 'My panel content' ) } + * + * ); + * ``` + * + * @return {WPElement} The WPElement to be rendered. + */ const PluginPrePublishPanel = ( { children, className, title, initialOpen = false } ) => ( ES5 + * ```js + * // Using ES5 syntax + * var __ = wp.i18n.__; + * var el = wp.element.createElement; + * var PanelBody = wp.components.PanelBody; + * var PluginSidebar = wp.editPost.PluginSidebar; + * + * function MyPluginSidebar() { + * return el( + * PluginSidebar, + * { + * name: 'my-sidebar', + * title: 'My sidebar title', + * icon: 'smiley', + * }, + * el( + * PanelBody, + * {}, + * __( 'My sidebar content' ) + * ) + * ); + * } + * ``` + * + * @example ESNext + * ```jsx + * // Using ESNext syntax + * const { __ } = wp.i18n; + * const { PanelBody } = wp.components; + * const { PluginSidebar } = wp.editPost; + * + * const MyPluginSidebar = () => ( + * + * + * { __( 'My sidebar content' ) } + * + * + * ); + * ``` + * + * @return {WPElement} Plugin sidebar component. + */ export default compose( withPluginContext( ( context, ownProps ) => { return {