Edit Post

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.

Installation

Install the module

npm install @wordpress/edit-post

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 in your code.

Extending the post 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 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.

API

initializeEditor

Initializes and returns an instance of Editor.

Parameters

• id string: Unique identifier for editor instance.
• postType string: 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 React.createElement( PluginBlockSettingsMenuItem, {
		allowedBlocks: [ 'core/paragraph' ],
		icon: 'dashicon-name',
		label: __( 'Menu item text' ),
		onClick: doOnClick,
	} );
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginBlockSettingsMenuItem } from '@wordpress/edit-post';

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 allowed list.
• props.icon [WPBlockTypeIconRender]: 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.
• props.small [boolean]: Whether to render the label or not.
• props.role [string]: The ARIA role for the menu item.

Returns

• Component: The component to be rendered.

PluginDocumentSettingPanel

Renders items below the Status & Availability panel in the Document Sidebar.

Usage

// Using ES5 syntax
var el = React.createElement;
var __ = wp.i18n.__;
var registerPlugin = wp.plugins.registerPlugin;
var PluginDocumentSettingPanel = wp.editPost.PluginDocumentSettingPanel;

function MyDocumentSettingPlugin() {
	return el(
		PluginDocumentSettingPanel,
		{
			className: 'my-document-setting-plugin',
			title: 'My Panel',
			name: 'my-panel',
		},
		__( 'My Document Setting Panel' )
	);
}

registerPlugin( 'my-document-setting-plugin', {
	render: MyDocumentSettingPlugin,
} );

// Using ESNext syntax
import { registerPlugin } from '@wordpress/plugins';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';

const MyDocumentSettingTest = () => (
	<PluginDocumentSettingPanel
		className="my-document-setting-plugin"
		title="My Panel"
		name="my-panel"
	>
		<p>My Document Setting Panel</p>
	</PluginDocumentSettingPanel>
);

registerPlugin( 'document-setting-test', { render: MyDocumentSettingTest } );

Parameters

• props Object: Component properties.
• props.name string: Required. A machine-friendly name for the panel.
• props.className [string]: An optional class name added to the row.
• props.title [string]: The title of the panel
• props.icon [WPBlockTypeIconRender]: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar.
• props.children Element: Children to be rendered

Returns

• Component: The component 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;
var moreIcon = React.createElement( 'svg' ); //... svg element.

function onButtonClick() {
	alert( 'Button clicked.' );
}

function MyButtonMoreMenuItem() {
	return React.createElement(
		PluginMoreMenuItem,
		{
			icon: moreIcon,
			onClick: onButtonClick,
		},
		__( 'My button title' )
	);
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginMoreMenuItem } from '@wordpress/edit-post';
import { more } from '@wordpress/icons';

function onButtonClick() {
	alert( 'Button clicked.' );
}

const MyButtonMoreMenuItem = () => (
	<PluginMoreMenuItem icon={ more } onClick={ onButtonClick }>
		{ __( 'My button title' ) }
	</PluginMoreMenuItem>
);

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 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

• Component: The component 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 React.createElement(
		PluginPostPublishPanel,
		{
			className: 'my-plugin-post-publish-panel',
			title: __( 'My panel title' ),
			initialOpen: true,
		},
		__( 'My panel content' )
	);
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginPostPublishPanel } from '@wordpress/edit-post';

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.
• props.icon [WPBlockTypeIconRender]: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar.
• props.children Element: Children to be rendered

Returns

• Component: The component to be rendered.

PluginPostStatusInfo

Renders a row in the Summary 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 React.createElement(
		PluginPostStatusInfo,
		{
			className: 'my-plugin-post-status-info',
		},
		__( 'My post status info' )
	);
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginPostStatusInfo } from '@wordpress/edit-post';

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.
• props.children Element: Children to be rendered.

Returns

• Component: The component 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 React.createElement(
		PluginPrePublishPanel,
		{
			className: 'my-plugin-pre-publish-panel',
			title: __( 'My panel title' ),
			initialOpen: true,
		},
		__( 'My panel content' )
	);
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginPrePublishPanel } from '@wordpress/edit-post';

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.
• props.icon [WPBlockTypeIconRender]: The Dashicon icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar.
• props.children Element: Children to be rendered

Returns

• Component: 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:

wp.data
	.dispatch( 'core/edit-post' )
	.openGeneralSidebar( 'plugin-name/sidebar-name' );

Related

• PluginSidebarMoreMenuItem

Usage

// Using ES5 syntax
var __ = wp.i18n.__;
var el = React.createElement;
var PanelBody = wp.components.PanelBody;
var PluginSidebar = wp.editPost.PluginSidebar;
var moreIcon = React.createElement( 'svg' ); //... svg element.

function MyPluginSidebar() {
	return el(
		PluginSidebar,
		{
			name: 'my-sidebar',
			title: 'My sidebar title',
			icon: moreIcon,
		},
		el( PanelBody, {}, __( 'My sidebar content' ) )
	);
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PanelBody } from '@wordpress/components';
import { PluginSidebar } from '@wordpress/edit-post';
import { more } from '@wordpress/icons';

const MyPluginSidebar = () => (
	<PluginSidebar name="my-sidebar" title="My sidebar title" icon={ more }>
		<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 the toolbar. When set to true it also automatically renders a corresponding menu item.
• props.icon [WPBlockTypeIconRender]: The Dashicon 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

// Using ES5 syntax
var __ = wp.i18n.__;
var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem;
var moreIcon = React.createElement( 'svg' ); //... svg element.

function MySidebarMoreMenuItem() {
	return React.createElement(
		PluginSidebarMoreMenuItem,
		{
			target: 'my-sidebar',
			icon: moreIcon,
		},
		__( 'My sidebar title' )
	);
}

// Using ESNext syntax
import { __ } from '@wordpress/i18n';
import { PluginSidebarMoreMenuItem } from '@wordpress/edit-post';
import { more } from '@wordpress/icons';

const MySidebarMoreMenuItem = () => (
	<PluginSidebarMoreMenuItem target="my-sidebar" icon={ more }>
		{ __( '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 the name prop you have given to that sidebar.
• props.icon [WPBlockTypeIconRender]: The Dashicon icon slug string, or an SVG WP element, to be rendered to the left of the menu item label.

Returns

• Component: The component to be rendered.

reinitializeEditor

Used to reinitialize the editor after an error. Now it's a deprecated noop function.

store

Store definition for the edit post namespace.

Related

• https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

Type

• 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 and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.