Edit Post Module for WordPress.
This package is meant to be used only with WordPress core. Feel free to use it in your own project but please keep in mind that it might never get fully documented.
Install the module
npm install @wordpress/edit-postThis package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.
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 for more information.
The components exported through the API can be used with the registerPlugin (see documentation) API.
They can be found in the global variable wp.editPost when defining wp-edit-post as a script dependency.
# initializeEditor
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
- 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).
# PluginBlockSettingsMenuItem
Renders a new item in the block settings menu.
Usage
// 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,
{
allowedBlocks: [ 'core/paragraph' ],
icon: 'dashicon-name',
label: __( 'Menu item text' ),
onClick: doOnClick,
}
);
}// 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 = () => (
<PluginBlockSettingsMenuItem
allowedBlocks=[ 'core/paragraph' ]
icon='dashicon-name'
label=__( 'Menu item text' )
onClick={ doOnClick } />
);Parameters
- props
Object: Component props. - props.allowedBlocks
[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 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.
Returns
WPElement: The WPElement to be rendered.
# 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
// 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' )
)
}// Using ESNext syntax
const { __ } = wp.i18n;
const { PluginMoreMenuItem } = wp.editPost;
function onButtonClick() {
alert( 'Button clicked.' );
}
const MyButtonMoreMenuItem = () => (
<PluginMoreMenuItem
icon="smiley"
onClick={ onButtonClick }
>
{ __( 'My button title' ) }
</PluginMoreMenuItem>
);Parameters
- props
Object: Component properties. - props.href
[string]: Whenhrefis provided then the menu item is represented as an anchor rather than button. It corresponds to thehrefattribute of the anchor. - props.icon
[(string|Element)]: The Dashicon 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 component.
Returns
WPElement: The element to be rendered.
# PluginPostPublishPanel
Renders provided content to the post-publish panel in the publish flow (side panel that opens after a user publishes the post).
Usage
// 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' )
);
}// Using ESNext syntax
const { __ } = wp.i18n;
const { PluginPostPublishPanel } = wp.editPost;
const MyPluginPostPublishPanel = () => (
<PluginPostPublishPanel
className="my-plugin-post-publish-panel"
title={ __( 'My panel title' ) }
initialOpen={ true }
>
{ __( 'My panel content' ) }
</PluginPostPublishPanel>
);Parameters
- 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.
Returns
WPElement: The WPElement to be rendered.
# PluginPostStatusInfo
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.
Usage
// 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' )
)
}// Using ESNext syntax
const { __ } = wp.i18n;
const { PluginPostStatusInfo } = wp.editPost;
const MyPluginPostStatusInfo = () => (
<PluginPostStatusInfo
className="my-plugin-post-status-info"
>
{ __( 'My post status info' ) }
</PluginPostStatusInfo>
);Parameters
- props
Object: Component properties. - props.className
[string]: An optional class name added to the row.
Returns
WPElement: The WPElement to be rendered.
# 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).
Usage
// 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' )
);
}// Using ESNext syntax
const { __ } = wp.i18n;
const { PluginPrePublishPanel } = wp.editPost;
const MyPluginPrePublishPanel = () => (
<PluginPrePublishPanel
className="my-plugin-pre-publish-panel"
title={ __( 'My panel title' ) }
initialOpen={ true }
>
{ __( 'My panel content' ) }
</PluginPrePublishPanel>
);Parameters
- 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.
Returns
WPElement: The WPElement to be rendered.
# 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 component or the wp.data.dispatch API:
wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/sidebar-name' );Related
- PluginSidebarMoreMenuItem
Usage
// 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' )
)
);
}// Using ESNext syntax
const { __ } = wp.i18n;
const { PanelBody } = wp.components;
const { PluginSidebar } = wp.editPost;
const MyPluginSidebar = () => (
<PluginSidebar
name="my-sidebar"
title="My sidebar title"
icon="smiley"
>
<PanelBody>
{ __( 'My sidebar content' ) }
</PanelBody>
</PluginSidebar>
);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 icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar.
Returns
WPElement: Plugin sidebar component.
# 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
// 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' )
)
}// Using ESNext syntax
const { __ } = wp.i18n;
const { PluginSidebarMoreMenuItem } = wp.editPost;
const MySidebarMoreMenuItem = () => (
<PluginSidebarMoreMenuItem
target="my-sidebar"
icon="smiley"
>
{ __( 'My sidebar title' ) }
</PluginSidebarMoreMenuItem>
);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 thenameprop you have given to that sidebar. - props.icon
[(string|Element)]: The Dashicon icon slug string, or an SVG WP element, to be rendered to the left of the menu item label.
Returns
WPElement: The element 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
- 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).
