UNPKG

13.1 kBMarkdownView Raw
1# Edit Post
2
3Edit Post Module for WordPress.
4
5> 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.
6
7## Installation
8
9Install the module
10
11```bash
12npm install @wordpress/edit-post
13```
14
15_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 ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
16
17## Extending the post editor UI
18
19Extending the editor UI can be accomplished with the `registerPlugin` API, allowing you to define all your plugin's UI elements in one place.
20
21Refer to [the plugins module documentation](/packages/plugins/README.md) for more information.
22
23The components exported through the API can be used with the `registerPlugin` ([see documentation](/packages/plugins/README.md)) API.
24They can be found in the global variable `wp.editPost` when defining `wp-edit-post` as a script dependency.
25
26## API
27
28<!-- START TOKEN(Autogenerated API docs) -->
29
30### initializeEditor
31
32[src/index.js#L66-L96](src/index.js#L66-L96)
33
34Initializes and returns an instance of Editor.
35
36The return value of this function is not necessary if we change where we
37call initializeEditor(). This is due to metaBox timing.
38
39**Parameters**
40
41- **id** `string`: Unique identifier for editor instance.
42- **postType** `Object`: Post type of the post to edit.
43- **postId** `Object`: ID of the post to edit.
44- **settings** `?Object`: Editor settings object.
45- **initialEdits** `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt).
46
47### PluginBlockSettingsMenuItem
48
49[src/index.js#L98-L98](src/index.js#L98-L98)
50
51Renders a new item in the block settings menu.
52
53**Usage**
54
55```js
56// Using ES5 syntax
57var __ = wp.i18n.__;
58var PluginBlockSettingsMenuItem = wp.editPost.PluginBlockSettingsMenuItem;
59
60function doOnClick(){
61 // To be called when the user clicks the menu item.
62}
63
64function MyPluginBlockSettingsMenuItem() {
65 return wp.element.createElement(
66 PluginBlockSettingsMenuItem,
67 {
68 allowedBlockNames: [ 'core/paragraph' ],
69 icon: 'dashicon-name',
70 label: __( 'Menu item text' ),
71 onClick: doOnClick,
72 }
73 );
74}
75```
76
77```jsx
78// Using ESNext syntax
79import { __ } from wp.i18n;
80import { PluginBlockSettingsMenuItem } from wp.editPost;
81
82const doOnClick = ( ) => {
83 // To be called when the user clicks the menu item.
84};
85
86const MyPluginBlockSettingsMenuItem = () => (
87 <PluginBlockSettingsMenuItem
88 allowedBlockNames=[ 'core/paragraph' ]
89 icon='dashicon-name'
90 label=__( 'Menu item text' )
91 onClick={ doOnClick } />
92);
93```
94
95**Parameters**
96
97- **props** `Object`: Component props.
98- **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.
99- **props.icon** `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element.
100- **props.label** `string`: The menu item text.
101- **props.onClick** `Function`: Callback function to be executed when the user click the menu item.
102
103**Returns**
104
105`WPElement`: The WPElement to be rendered.
106
107### PluginMoreMenuItem
108
109[src/index.js#L99-L99](src/index.js#L99-L99)
110
111Renders 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.
112The text within the component appears as the menu item label.
113
114**Usage**
115
116```js
117// Using ES5 syntax
118var __ = wp.i18n.__;
119var PluginMoreMenuItem = wp.editPost.PluginMoreMenuItem;
120
121function onButtonClick() {
122 alert( 'Button clicked.' );
123}
124
125function MyButtonMoreMenuItem() {
126 return wp.element.createElement(
127 PluginMoreMenuItem,
128 {
129 icon: 'smiley',
130 onClick: onButtonClick
131 },
132 __( 'My button title' )
133 )
134}
135```
136
137```jsx
138// Using ESNext syntax
139const { __ } = wp.i18n;
140const { PluginMoreMenuItem } = wp.editPost;
141
142function onButtonClick() {
143 alert( 'Button clicked.' );
144}
145
146const MyButtonMoreMenuItem = () => (
147 <PluginMoreMenuItem
148 icon="smiley"
149 onClick={ onButtonClick }
150 >
151 { __( 'My button title' ) }
152 </PluginMoreMenuItem>
153);
154```
155
156**Parameters**
157
158- **props** `Object`: Component properties.
159- **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.
160- **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.
161- **props.onClick** `[Function]`: The callback function to be executed when the user clicks the menu item.
162- **props.other** `[...*]`: Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component.
163
164**Returns**
165
166`WPElement`: The element to be rendered.
167
168### PluginPostPublishPanel
169
170[src/index.js#L100-L100](src/index.js#L100-L100)
171
172Renders provided content to the post-publish panel in the publish flow
173(side panel that opens after a user publishes the post).
174
175**Usage**
176
177```js
178// Using ES5 syntax
179var __ = wp.i18n.__;
180var PluginPostPublishPanel = wp.editPost.PluginPostPublishPanel;
181
182function MyPluginPostPublishPanel() {
183 return wp.element.createElement(
184 PluginPostPublishPanel,
185 {
186 className: 'my-plugin-post-publish-panel',
187 title: __( 'My panel title' ),
188 initialOpen: true,
189 },
190 __( 'My panel content' )
191 );
192}
193```
194
195```jsx
196// Using ESNext syntax
197const { __ } = wp.i18n;
198const { PluginPostPublishPanel } = wp.editPost;
199
200const MyPluginPostPublishPanel = () => (
201 <PluginPostPublishPanel
202 className="my-plugin-post-publish-panel"
203 title={ __( 'My panel title' ) }
204 initialOpen={ true }
205 >
206 { __( 'My panel content' ) }
207 </PluginPostPublishPanel>
208);
209```
210
211**Parameters**
212
213- **props** `Object`: Component properties.
214- **props.className** `[string]`: An optional class name added to the panel.
215- **props.title** `[string]`: Title displayed at the top of the panel.
216- **props.initialOpen** `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened.
217
218**Returns**
219
220`WPElement`: The WPElement to be rendered.
221
222### PluginPostStatusInfo
223
224[src/index.js#L101-L101](src/index.js#L101-L101)
225
226Renders a row in the Status & Visibility panel of the Document sidebar.
227It should be noted that this is named and implemented around the function it serves
228and not its location, which may change in future iterations.
229
230**Usage**
231
232```js
233// Using ES5 syntax
234var __ = wp.i18n.__;
235var PluginPostStatusInfo = wp.editPost.PluginPostStatusInfo;
236
237function MyPluginPostStatusInfo() {
238 return wp.element.createElement(
239 PluginPostStatusInfo,
240 {
241 className: 'my-plugin-post-status-info',
242 },
243 __( 'My post status info' )
244 )
245}
246```
247
248```jsx
249// Using ESNext syntax
250const { __ } = wp.i18n;
251const { PluginPostStatusInfo } = wp.editPost;
252
253const MyPluginPostStatusInfo = () => (
254 <PluginPostStatusInfo
255 className="my-plugin-post-status-info"
256 >
257 { __( 'My post status info' ) }
258 </PluginPostStatusInfo>
259);
260```
261
262**Parameters**
263
264- **props** `Object`: Component properties.
265- **props.className** `[string]`: An optional class name added to the row.
266
267**Returns**
268
269`WPElement`: The WPElement to be rendered.
270
271### PluginPrePublishPanel
272
273[src/index.js#L102-L102](src/index.js#L102-L102)
274
275Renders provided content to the pre-publish side panel in the publish flow
276(side panel that opens when a user first pushes "Publish" from the main editor).
277
278**Usage**
279
280```js
281// Using ES5 syntax
282var __ = wp.i18n.__;
283var PluginPrePublishPanel = wp.editPost.PluginPrePublishPanel;
284
285function MyPluginPrePublishPanel() {
286 return wp.element.createElement(
287 PluginPrePublishPanel,
288 {
289 className: 'my-plugin-pre-publish-panel',
290 title: __( 'My panel title' ),
291 initialOpen: true,
292 },
293 __( 'My panel content' )
294 );
295}
296```
297
298```jsx
299// Using ESNext syntax
300const { __ } = wp.i18n;
301const { PluginPrePublishPanel } = wp.editPost;
302
303const MyPluginPrePublishPanel = () => (
304 <PluginPrePublishPanel
305 className="my-plugin-pre-publish-panel"
306 title={ __( 'My panel title' ) }
307 initialOpen={ true }
308 >
309 { __( 'My panel content' ) }
310 </PluginPrePublishPanel>
311);
312```
313
314**Parameters**
315
316- **props** `Object`: Component props.
317- **props.className** `[string]`: An optional class name added to the panel.
318- **props.title** `[string]`: Title displayed at the top of the panel.
319- **props.initialOpen** `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened.
320
321**Returns**
322
323`WPElement`: The WPElement to be rendered.
324
325### PluginSidebar
326
327[src/index.js#L103-L103](src/index.js#L103-L103)
328
329Renders a sidebar when activated. The contents within the `PluginSidebar` will appear as content within the sidebar.
330If you wish to display the sidebar, you can with use the `PluginSidebarMoreMenuItem` component or the `wp.data.dispatch` API:
331
332```js
333wp.data.dispatch( 'core/edit-post' ).openGeneralSidebar( 'plugin-name/sidebar-name' );
334```
335
336**Related**
337
338- PluginSidebarMoreMenuItem
339
340**Usage**
341
342```js
343// Using ES5 syntax
344var __ = wp.i18n.__;
345var el = wp.element.createElement;
346var PanelBody = wp.components.PanelBody;
347var PluginSidebar = wp.editPost.PluginSidebar;
348
349function MyPluginSidebar() {
350 return el(
351 PluginSidebar,
352 {
353 name: 'my-sidebar',
354 title: 'My sidebar title',
355 icon: 'smiley',
356 },
357 el(
358 PanelBody,
359 {},
360 __( 'My sidebar content' )
361 )
362 );
363}
364```
365
366```jsx
367// Using ESNext syntax
368const { __ } = wp.i18n;
369const { PanelBody } = wp.components;
370const { PluginSidebar } = wp.editPost;
371
372const MyPluginSidebar = () => (
373 <PluginSidebar
374 name="my-sidebar"
375 title="My sidebar title"
376 icon="smiley"
377 >
378 <PanelBody>
379 { __( 'My sidebar content' ) }
380 </PanelBody>
381 </PluginSidebar>
382);
383```
384
385**Parameters**
386
387- **props** `Object`: Element props.
388- **props.name** `string`: A string identifying the sidebar. Must be unique for every sidebar registered within the scope of your plugin.
389- **props.className** `[string]`: An optional class name added to the sidebar body.
390- **props.title** `string`: Title displayed at the top of the sidebar.
391- **props.isPinnable** `[boolean]`: Whether to allow to pin sidebar to toolbar.
392- **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.
393
394**Returns**
395
396`WPElement`: Plugin sidebar component.
397
398### PluginSidebarMoreMenuItem
399
400[src/index.js#L104-L104](src/index.js#L104-L104)
401
402Renders a menu item in `Plugins` group in `More Menu` drop down,
403and can be used to activate the corresponding `PluginSidebar` component.
404The text within the component appears as the menu item label.
405
406**Usage**
407
408```js
409// Using ES5 syntax
410var __ = wp.i18n.__;
411var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem;
412
413function MySidebarMoreMenuItem() {
414 return wp.element.createElement(
415 PluginSidebarMoreMenuItem,
416 {
417 target: 'my-sidebar',
418 icon: 'smiley',
419 },
420 __( 'My sidebar title' )
421 )
422}
423```
424
425```jsx
426// Using ESNext syntax
427const { __ } = wp.i18n;
428const { PluginSidebarMoreMenuItem } = wp.editPost;
429
430const MySidebarMoreMenuItem = () => (
431 <PluginSidebarMoreMenuItem
432 target="my-sidebar"
433 icon="smiley"
434 >
435 { __( 'My sidebar title' ) }
436 </PluginSidebarMoreMenuItem>
437);
438```
439
440**Parameters**
441
442- **props** `Object`: Component props.
443- **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.
444- **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.
445
446**Returns**
447
448`WPElement`: The element to be rendered.
449
450### reinitializeEditor
451
452[src/index.js#L35-L50](src/index.js#L35-L50)
453
454Reinitializes the editor after the user chooses to reboot the editor after
455an unhandled error occurs, replacing previously mounted editor element using
456an initial state from prior to the crash.
457
458**Parameters**
459
460- **postType** `Object`: Post type of the post to edit.
461- **postId** `Object`: ID of the post to edit.
462- **target** `Element`: DOM node in which editor is rendered.
463- **settings** `?Object`: Editor settings object.
464- **initialEdits** `Object`: Programmatic edits to apply initially, to be considered as non-user-initiated (bypass for unsaved changes prompt).
465
466<!-- END TOKEN(Autogenerated API docs) -->
467
468<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>