From 9098593e02e25b57104704a9b62a43d68a47c550 Mon Sep 17 00:00:00 2001 From: Tetsuaki Hamano Date: Tue, 9 Aug 2022 20:55:25 +0900 Subject: [PATCH 1/4] Autogenerate edit site API docs --- packages/edit-site/README.md | 204 +++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) diff --git a/packages/edit-site/README.md b/packages/edit-site/README.md index d209d914ea91f..fed01f4bd6359 100644 --- a/packages/edit-site/README.md +++ b/packages/edit-site/README.md @@ -28,6 +28,210 @@ initialize( '#editor-root', blockEditorSettings ); _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._ +## Extending the site editor UI + +Extending the editor UI can be accomplished with the `registerPlugin` API, allowing you to define all your plugin's UI elements in one place. + +Refer to [the plugins module documentation](https://github.com/WordPress/gutenberg/tree/HEAD/packages/plugins/README.md) for more information. + +The components exported through the API can be used with the `registerPlugin` ([see documentation](https://github.com/WordPress/gutenberg/tree/HEAD/packages/plugins/README.md)) API. +They can be found in the global variable `wp.editSite` when defining `wp-edit-site` as a script dependency. + +## API + + + +### initializeEditor + +Initializes the site editor screen. + +_Parameters_ + +- _id_ `string`: ID of the root element to render the screen in. +- _settings_ `Object`: Editor settings. + +### PluginMoreMenuItem + +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. + +_Usage_ + +```js +// Using ES5 syntax +var __ = wp.i18n.__; +var PluginMoreMenuItem = wp.editSite.PluginMoreMenuItem; +var moreIcon = wp.element.createElement( 'svg' ); //... svg element. + +function onButtonClick() { + alert( 'Button clicked.' ); +} + +function MyButtonMoreMenuItem() { + return wp.element.createElement( + PluginMoreMenuItem, + { + icon: moreIcon, + onClick: onButtonClick, + }, + __( 'My button title' ) + ); +} +``` + +```jsx +// Using ESNext syntax +import { __ } from '@wordpress/i18n'; +import { PluginMoreMenuItem } from '@wordpress/edit-site'; +import { more } from '@wordpress/icons'; + +function onButtonClick() { + alert( 'Button clicked.' ); +} + +const MyButtonMoreMenuItem = () => ( + + { __( 'My button title' ) } + +); +``` + +_Parameters_ + +- _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_ `[WPBlockTypeIconRender]`: 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 [Button](/packages/components/src/button/README.md) component. + +_Returns_ + +- `WPComponent`: The component to be rendered. + +### PluginSidebar + +Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar. +It also automatically renders a corresponding `PluginSidebarMenuItem` component when `isPinnable` flag is set to `true`. +If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API: + +```js +wp.data + .dispatch( 'core/edit-site' ) + .openGeneralSidebar( 'plugin-name/sidebar-name' ); +``` + +_Related_ + +- PluginSidebarMoreMenuItem + +_Usage_ + +```js +// Using ES5 syntax +var __ = wp.i18n.__; +var el = wp.element.createElement; +var PanelBody = wp.components.PanelBody; +var PluginSidebar = wp.editSite.PluginSidebar; +var moreIcon = wp.element.createElement( 'svg' ); //... svg element. + +function MyPluginSidebar() { + return el( + PluginSidebar, + { + name: 'my-sidebar', + title: 'My sidebar title', + icon: moreIcon, + }, + el( PanelBody, {}, __( 'My sidebar content' ) ) + ); +} +``` + +```jsx +// Using ESNext syntax +import { __ } from '@wordpress/i18n'; +import { PanelBody } from '@wordpress/components'; +import { PluginSidebar } from '@wordpress/edit-site'; +import { more } from '@wordpress/icons'; + +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 the toolbar. When set to `true` it also automatically renders a corresponding menu item. +- _props.icon_ `[WPBlockTypeIconRender]`: 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. + +### PluginSidebarMoreMenuItem + +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_ + +```js +// Using ES5 syntax +var __ = wp.i18n.__; +var PluginSidebarMoreMenuItem = wp.editSite.PluginSidebarMoreMenuItem; +var moreIcon = wp.element.createElement( 'svg' ); //... svg element. + +function MySidebarMoreMenuItem() { + return wp.element.createElement( + PluginSidebarMoreMenuItem, + { + target: 'my-sidebar', + icon: moreIcon, + }, + __( 'My sidebar title' ) + ); +} +``` + +```jsx +// Using ESNext syntax +import { __ } from '@wordpress/i18n'; +import { PluginSidebarMoreMenuItem } from '@wordpress/edit-site'; +import { more } from '@wordpress/icons'; + +const MySidebarMoreMenuItem = () => ( + + { __( 'My sidebar title' ) } + +); +``` + +_Parameters_ + +- _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_ `[WPBlockTypeIconRender]`: 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_ + +- `WPComponent`: The component to be rendered. + +### reinitializeEditor + +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. + +_Parameters_ + +- _target_ `Element`: DOM node in which editor is rendered. +- _settings_ `?Object`: Editor settings object. + + + ## Contributing to this package This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. From c7ac021c78732d47911ea1a37d6814d0d5f23a69 Mon Sep 17 00:00:00 2001 From: Tetsuaki Hamano Date: Tue, 9 Aug 2022 21:25:16 +0900 Subject: [PATCH 2/4] Add notes about edit-site --- docs/reference-guides/slotfills/plugin-more-menu-item.md | 2 ++ .../slotfills/plugin-sidebar-more-menu-item.md | 2 ++ docs/reference-guides/slotfills/plugin-sidebar.md | 2 ++ packages/plugins/README.md | 3 +++ packages/plugins/src/api/index.ts | 3 +++ 5 files changed, 12 insertions(+) diff --git a/docs/reference-guides/slotfills/plugin-more-menu-item.md b/docs/reference-guides/slotfills/plugin-more-menu-item.md index 6a53c029b10dd..942af8f85af2d 100644 --- a/docs/reference-guides/slotfills/plugin-more-menu-item.md +++ b/docs/reference-guides/slotfills/plugin-more-menu-item.md @@ -2,6 +2,8 @@ This slot will add a new item to the More Tools & Options section. +Note: In the site editor, import `PluginMoreMenuItem` from `@wordpress/edit-site` instead. + ## Example ```js diff --git a/docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md b/docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md index 4d32d754578cc..157d503954de3 100644 --- a/docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md +++ b/docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md @@ -3,6 +3,8 @@ This slot allows the creation of a `` with a menu item that when clicked will expand the sidebar to the appropriate Plugin section. This is done by setting the `target` on `` to match the `name` on the `` +Note: In the site editor, import `PluginSidebar` and `PluginSidebarMoreMenuItem` from `@wordpress/edit-site` instead. + ## Example ```js diff --git a/docs/reference-guides/slotfills/plugin-sidebar.md b/docs/reference-guides/slotfills/plugin-sidebar.md index 56d87ea1fc1be..368ddae50a1c9 100644 --- a/docs/reference-guides/slotfills/plugin-sidebar.md +++ b/docs/reference-guides/slotfills/plugin-sidebar.md @@ -3,6 +3,8 @@ This slot allows for adding items into the Gutenberg Toolbar. Using this slot will add an icon to the bar that, when clicked, will open a sidebar with the content of the items wrapped in the `` component. +Note: In the site editor, import `PluginSidebar` from `@wordpress/edit-site` instead. + ## Example ```js diff --git a/packages/plugins/README.md b/packages/plugins/README.md index e9e5a704aeca7..9a2a768144447 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -88,6 +88,7 @@ _Usage_ // Using ES5 syntax var el = React.createElement; var Fragment = wp.element.Fragment; +// In the site editor, import PluginSidebar and PluginSidebarMoreMenuItem from wp.editSite instead. var PluginSidebar = wp.editPost.PluginSidebar; var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem; var registerPlugin = wp.plugins.registerPlugin; @@ -123,6 +124,8 @@ registerPlugin( 'plugin-name', { ```js // Using ESNext syntax + +// In the site editor, import PluginSidebar and PluginSidebarMoreMenuItem from @wordpress/edit-site instead. import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post'; import { registerPlugin } from '@wordpress/plugins'; import { more } from '@wordpress/icons'; diff --git a/packages/plugins/src/api/index.ts b/packages/plugins/src/api/index.ts index 45c8f93163419..0fc97eb270375 100644 --- a/packages/plugins/src/api/index.ts +++ b/packages/plugins/src/api/index.ts @@ -58,6 +58,7 @@ const plugins = {} as Record< string, WPPlugin >; * // Using ES5 syntax * var el = React.createElement; * var Fragment = wp.element.Fragment; + * // In the site editor, import PluginSidebar and PluginSidebarMoreMenuItem from wp.editSite instead. * var PluginSidebar = wp.editPost.PluginSidebar; * var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem; * var registerPlugin = wp.plugins.registerPlugin; @@ -94,6 +95,8 @@ const plugins = {} as Record< string, WPPlugin >; * @example * ```js * // Using ESNext syntax + * + * // In the site editor, import PluginSidebar and PluginSidebarMoreMenuItem from @wordpress/edit-site instead. * import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post'; * import { registerPlugin } from '@wordpress/plugins'; * import { more } from '@wordpress/icons'; From f10488785b81388100e304b44463aeb7bc0d23c7 Mon Sep 17 00:00:00 2001 From: Tetsuaki Hamano Date: Sat, 6 May 2023 00:46:57 +0900 Subject: [PATCH 3/4] Rebase and build docs --- packages/edit-site/README.md | 39 ++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/packages/edit-site/README.md b/packages/edit-site/README.md index fed01f4bd6359..c2af23885bf90 100644 --- a/packages/edit-site/README.md +++ b/packages/edit-site/README.md @@ -52,8 +52,7 @@ _Parameters_ ### PluginMoreMenuItem -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. +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. _Usage_ @@ -110,9 +109,7 @@ _Returns_ ### PluginSidebar -Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar. -It also automatically renders a corresponding `PluginSidebarMenuItem` component when `isPinnable` flag is set to `true`. -If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API: +Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar. It also automatically renders a corresponding `PluginSidebarMenuItem` component when `isPinnable` flag is set to `true`. If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API: ```js wp.data @@ -172,9 +169,7 @@ _Parameters_ ### PluginSidebarMoreMenuItem -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. +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_ @@ -219,16 +214,30 @@ _Returns_ - `WPComponent`: The component to be rendered. -### reinitializeEditor +### PluginTemplateSettingPanel -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. +Renders items in the Template Sidebar below the main information like the Template Card. -_Parameters_ +_Usage_ + +```jsx +// Using ESNext syntax +import { PluginTemplateSettingPanel } from '@wordpress/edit-site'; + +const MyTemplateSettingTest = () => ( + +

Hello, World!

+ +); +``` + +_Returns_ + +- `WPComponent`: The component to be rendered. + +### reinitializeEditor -- _target_ `Element`: DOM node in which editor is rendered. -- _settings_ `?Object`: Editor settings object. +Undocumented declaration. From cb9d0edb3c7941a525ea05a1707662c620494d43 Mon Sep 17 00:00:00 2001 From: Tetsuaki Hamano Date: Thu, 28 Dec 2023 23:40:37 +0900 Subject: [PATCH 4/4] Rebuild docs --- packages/edit-site/README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/packages/edit-site/README.md b/packages/edit-site/README.md index c2af23885bf90..a1ae0f05f6717 100644 --- a/packages/edit-site/README.md +++ b/packages/edit-site/README.md @@ -105,7 +105,7 @@ _Parameters_ _Returns_ -- `WPComponent`: The component to be rendered. +- `Component`: The component to be rendered. ### PluginSidebar @@ -212,7 +212,7 @@ _Parameters_ _Returns_ -- `WPComponent`: The component to be rendered. +- `Component`: The component to be rendered. ### PluginTemplateSettingPanel @@ -233,12 +233,16 @@ const MyTemplateSettingTest = () => ( _Returns_ -- `WPComponent`: The component to be rendered. +- `Component`: The component to be rendered. ### reinitializeEditor Undocumented declaration. +### store + +Undocumented declaration. + ## Contributing to this package