From fe82b70961a5b607b8030bddfe8cdd34975b4b62 Mon Sep 17 00:00:00 2001 From: Tetsuaki Hamano Date: Tue, 9 Aug 2022 20:55:25 +0900 Subject: [PATCH] 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.