Editor: Add extensibility to PreviewOptions v2 #64644

lezama · 2024-08-20T13:18:20Z

Extend Preview Dropdown with Plugin API

Resolves #25309

What?

This PR introduces a new API to extend the Preview dropdown menu in the post/page editor. It builds upon the work done in #50605, #36119, and #31984, focusing specifically on allowing plugins to add custom menu items to the Preview dropdown.

Key features:

Introduces PreviewDropdownMenuItem component for adding custom items to the Preview dropdown
Allows plugins to add menu items with custom titles and click handlers
Maintains the existing Preview dropdown structure while allowing for extensibility

Why?

This extension point allows for greater flexibility in preview functionality, enabling plugin developers to integrate custom preview options seamlessly into the WordPress editor. It addresses the need for varied publishing flows and tools, such as:

Custom format previews (e.g., AMP, social media shares)
Previewing content with different access restrictions or user roles
Specialized preview modes (e.g., dark mode, email format)

How?

Utilizes the existing ActionItem component from @wordpress/interface
Implements a slot/fill pattern to inject custom menu items into the Preview dropdown
Maintains the declarative nature of the API, allowing for future UI changes without breaking plugin implementations

Testing Instructions

Import the PreviewDropdownMenuItem component in your plugin:

import { PreviewDropdownMenuItem } from '@wordpress/editor';

Implement a custom menu item:

const CustomPreviewMenuItem = () => (
  <PreviewDropdownMenuItem
    onClick={ () => {
      // Your custom preview logic
    } }
  >
    Custom Preview
  </PreviewDropdownMenuItem>
);

Register your plugin with the custom menu item.
Open the post/page editor and check the Preview dropdown for your custom menu item.
Click the custom menu item and verify that your onClick handler is called.

Testing Instructions for Keyboard

Open the post/page editor.
Use Tab to navigate to the Preview dropdown button.
Press Enter or Space to open the dropdown menu.
Use arrow keys to navigate to your custom menu item.
Press Enter to activate the custom menu item.
Verify that the custom action is triggered.

Screenshots or screencast

No icon:

With icon:

More than one item:

Future Considerations

Allow for grouping of custom preview options
Enable custom preview canvas or sizes
Add support for item selection within custom groups

This PR lays the groundwork for these future enhancements while providing immediate value to plugin developers wanting to extend the preview functionality.

github-actions · 2024-08-20T13:18:45Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @lezama! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

github-actions · 2024-08-20T16:55:56Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: lezama <migueluy@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: simison <simison@git.wordpress.org>
Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: fumikito <takahashi_fumiki@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

simison · 2024-08-22T14:14:00Z

Unrelated to these code changes, but it's now more noticeable how the "new tab" preview is inset more compared to other items:

Seems like a good follow-up fix in separate PR.

simison · 2024-08-22T14:25:16Z

@youknowriad @lezama :

Right now, this extends preview dropdown in post, page and site editors. What do you think about restricting v1 just to post editor. We can then see how it gets used, and allow extending page/post editor next up?
- If we allow extending dropdown in all editors, we should figure out how plugin extenders can limit to just one editor, and how their custom code can know about the editor context.
Hesitant allowing custom icons yet, but not a strong opinion. Mostly thinking that later we want to allow multi-selections with check mark, and it's hard to tell how the icon API then should look like in that scenario.

fabiankaegy · 2024-08-27T07:21:34Z

Slightly off topic question here, but would we also be open to allowing extenders to define their own "Preview" modes for inside the editor? Similar to how core is currently working on the new "50%" version it would be super valuable to register custom preview sizes.

Mamaduka · 2024-08-28T05:48:04Z

packages/editor/src/components/plugin-preview-dropdown-item/index.js

+export default compose(
+	withPluginContext( ( context, ownProps ) => {
+		return {
+			as: ownProps.as ?? MenuItem,
+			icon: ownProps.icon || context.icon,
+			name: 'core/plugin-preview-dropdown-menu',
+		};
+	} )
+)( ActionItem );


We can probably drop the withPluginContext. It's only here for icon context, and as @simison noted, there's no need for inheriting icons just yet.

The note mentioned above for clarity:

Hesitant allowing custom icons yet, but not a strong opinion. Mostly thinking that later we want to allow multi-selections with check mark, and it's hard to tell how the icon API then should look like in that scenario.

It's all supported out of the box for the PluginMoreMenuItem:

Whenever, the sidebar is selected, it's reflected in the menu with the checkmark icon ✔️. Let's not limit the options that are supported out of the box like the icon that get inherited for all fills. That's the part that makes the More Menu item behave as a checkbox:

gutenberg/packages/editor/src/components/plugin-sidebar-more-menu-item/index.js

Lines 56 to 63 in 71e0fae

<ComplementaryAreaMoreMenuItem

// Menu item is marked with unstable prop for backward compatibility.

// @see https://github.com/WordPress/gutenberg/issues/14457

__unstableExplicitMenuItem

scope="core"

{ ...props }

/>

);

gutenberg/packages/interface/src/components/complementary-area-more-menu-item/index.js

Lines 43 to 44 in 71e0fae

role="menuitemcheckbox"

selectedIcon={ check }

Then, if we want to keep the icon from the plugin context, let's use the usePluginContext hook instead of compose and withPluginContext.

If usePluginContext exist, then it would be so much more up to recent React standards 😄

gziolo

If we allow extending dropdown in all editors, we should figure out how plugin extenders can limit to just one editor, and how their custom code can know about the editor context.

The idea was that there would be the scope defined by the plugin's author when registering the plugin that would allow limiting where all fills gets injected. See https://github.com/WordPress/gutenberg/blob/trunk/packages/plugins/README.md#pluginarea:

import { PluginArea } from '@wordpress/plugins';

const Layout = () => (
	<div>
		Content of the page
		<PluginArea scope="my-page" />
	</div>
);

However, only the default scope is used in all editors, so it doesn't work in practice.

packages/editor/src/components/plugin-preview-dropdown-item/index.js

gziolo · 2024-08-28T07:11:37Z

packages/editor/src/components/plugin-preview-dropdown-item/index.js

+export default compose(
+	withPluginContext( ( context, ownProps ) => {
+		return {
+			as: ownProps.as ?? MenuItem,
+			icon: ownProps.icon || context.icon,
+			name: 'core/plugin-preview-dropdown-menu',
+		};
+	} )
+)( ActionItem );


The note mentioned above for clarity:

Hesitant allowing custom icons yet, but not a strong opinion. Mostly thinking that later we want to allow multi-selections with check mark, and it's hard to tell how the icon API then should look like in that scenario.

It's all supported out of the box for the PluginMoreMenuItem:

Whenever, the sidebar is selected, it's reflected in the menu with the checkmark icon ✔️. Let's not limit the options that are supported out of the box like the icon that get inherited for all fills. That's the part that makes the More Menu item behave as a checkbox:

gutenberg/packages/editor/src/components/plugin-sidebar-more-menu-item/index.js

Lines 56 to 63 in 71e0fae

<ComplementaryAreaMoreMenuItem

// Menu item is marked with unstable prop for backward compatibility.

// @see https://github.com/WordPress/gutenberg/issues/14457

__unstableExplicitMenuItem

scope="core"

{ ...props }

/>

);

gutenberg/packages/interface/src/components/complementary-area-more-menu-item/index.js

Lines 43 to 44 in 71e0fae

role="menuitemcheckbox"

selectedIcon={ check }

gziolo · 2024-08-28T07:57:25Z

This PR introduces a new API to extend the Preview dropdown menu in the post/page editor. It builds upon the work done in #50605, #36119, and #31984, focusing specifically on allowing plugins to add custom menu items to the Preview dropdown.

Yes, there have been a few attempts in the past. Thank you so much for giving it another go. From my perspective, the only missing pieces are e2e tests (maybe one test with a supporting plugin registration is enough) that cover the extension point. All similar e2e tests live in https://github.com/WordPress/gutenberg/blob/trunk/test/e2e/specs/editor/plugins/plugins-api.spec.js.

Looking through the existing names for fills:

I would favor renaming PluginPreviewDropdownMenuItem to PluginPreviewMenuItem as the dropdown part is only an implementation detail that could change over time.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

tests

lezama · 2024-08-30T18:35:23Z

I would favor renaming PluginPreviewDropdownMenuItem to PluginPreviewMenuItem

Good call @gziolo.

From my perspective, the only missing pieces are e2e tests

Done :)

lezama · 2024-08-30T18:53:15Z

Slightly off topic question here, but would we also be open to allowing extenders to define their own "Preview" modes for inside the editor?

@fabiankaegy for this initial effort, I would maintain the separation of plugins and core actions, similar to the setup in the 'More' menu.

youknowriad · 2024-09-02T13:08:59Z

Sorry a bit late here

Right now, this extends preview dropdown in post, page and site editors. What do you think about restricting v1 just to post editor. We can then see how it gets used, and allow extending page/post editor next up?
If we allow extending dropdown in all editors, we should figure out how plugin extenders can limit to just one editor, and how their custom code can know about the editor context.

I don't think we should limit any feature per "editor". We should not see post/page editor as separate from site editor. These should be seen as the same editor. The extenders shouldn't ask themselves whether they should limit their usage to one editor, instead they should ask themselves whether they should limit their extensions per post type. More on this in the last section of this post https://make.wordpress.org/core/2024/06/18/editor-unified-extensibility-apis-in-6-6/

youknowriad · 2024-09-02T13:11:37Z

This is looking good to me. I leave the final call for the others.

youknowriad · 2024-09-02T13:13:10Z

The idea was that there would be the scope defined by the plugin's author when registering the plugin that would allow limiting where all fills gets injected. See https://github.com/WordPress/gutenberg/blob/trunk/packages/plugins/README.md#pluginarea:

Yes, I also found that our approach with any random numbers of slot/fills used within the same registerPlugin call is not optimal in terms of performance and it doesn't provide much information to the framework to orchestrate the rendering and the plugins properly but the ship has sailed here, a change to that right now would be a big project and it's probably not the right time for it.

gziolo

All feedback addressed. I tested it using the plugin created to e2e tests and it all works great:

There is some misalignment with the "preview in new tab" icon, but it's a preexisting issue. Thank you for taking it to the finish line. We will need to include this change in the dev notes for WordPress 6.7.

mtias · 2024-09-05T02:38:46Z

Thanks for driving this one through!

lezama added 3 commits August 20, 2024 10:08

add plugin-preview-dropdown-item

3b94038

Add slot

f30edaf

export PluginPreviewDropdownItem

290072b

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Aug 20, 2024

lezama mentioned this pull request Aug 20, 2024

Test: PluginPreviewMenuItem Automattic/jetpack#38972

Closed

3 tasks

lezama marked this pull request as ready for review August 20, 2024 16:55

annezazu mentioned this pull request Aug 21, 2024

Your so-called preview tool is wrong all the time. Get rid of it finally! Allow us to preview pages with ONE click! #52105

Closed

simison self-requested a review August 22, 2024 14:05

simison added the [Feature] Extensibility The ability to extend blocks or the editing experience label Aug 22, 2024

simison added the [Type] New API New API to be used by plugin developers or package users. label Aug 22, 2024

simison requested a review from youknowriad August 22, 2024 14:16

simison mentioned this pull request Aug 22, 2024

Add extensibility to PreviewOptions #50605

Closed

gziolo self-requested a review August 23, 2024 18:04

fabiankaegy added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Aug 27, 2024

Mamaduka reviewed Aug 28, 2024

View reviewed changes

gziolo reviewed Aug 28, 2024

View reviewed changes

gziolo requested review from ryanwelcher and ndiego August 28, 2024 07:59

lezama and others added 4 commits August 28, 2024 10:23

add registerPlugin example

095e3aa

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

example import from @wordpress/editor

6b926ab

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>

rename to PluginPreviewMenuItem

1a975c8

add tests

bf99ae0

tests

lezama requested review from ntwb and nerrad as code owners August 30, 2024 18:33

lezama requested a review from ajitbohra as a code owner August 30, 2024 18:33

gziolo changed the title ~~Add extensibility to PreviewOptions v2~~ Editor: Add extensibility to PreviewOptions v2 Sep 1, 2024

gziolo approved these changes Sep 3, 2024

View reviewed changes

gziolo merged commit 9d4f918 into WordPress:trunk Sep 3, 2024
63 checks passed

github-actions bot added this to the Gutenberg 19.2 milestone Sep 3, 2024

This was referenced Sep 3, 2024

Add extensibility to PreviewOptions #36119

Closed

Make the Preview Menu extensible #31984

Closed

Tracking: A curated list of high-priority extensibility issues and enhancements #64848

Open

simison mentioned this pull request Sep 3, 2024

Allow extending editor preview in more ways #65005

Open

annezazu mentioned this pull request Sep 6, 2024

Set custom preview-options #21235

Closed

skorasaurus mentioned this pull request Sep 6, 2024

Print CSS preview in editor #34655

Open

WontonSam mentioned this pull request Sep 12, 2024

[Snyk] Upgrade @wordpress/eslint-plugin from 11.1.0 to 20.3.0 WontonSam/woocommerce-admin#266

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editor: Add extensibility to PreviewOptions v2 #64644

Editor: Add extensibility to PreviewOptions v2 #64644

lezama commented Aug 20, 2024 •

edited

Loading

github-actions bot commented Aug 20, 2024

github-actions bot commented Aug 20, 2024 •

edited

Loading

simison commented Aug 22, 2024

simison commented Aug 22, 2024

fabiankaegy commented Aug 27, 2024

Mamaduka Aug 28, 2024

gziolo Aug 28, 2024

Mamaduka Aug 28, 2024

gziolo Aug 28, 2024

gziolo left a comment

gziolo Aug 28, 2024

gziolo commented Aug 28, 2024

lezama commented Aug 30, 2024 •

edited

Loading

lezama commented Aug 30, 2024

youknowriad commented Sep 2, 2024

youknowriad commented Sep 2, 2024

youknowriad commented Sep 2, 2024

gziolo left a comment

mtias commented Sep 5, 2024

	<ComplementaryAreaMoreMenuItem
	// Menu item is marked with unstable prop for backward compatibility.
	// @see https://github.com/WordPress/gutenberg/issues/14457
	__unstableExplicitMenuItem
	scope="core"
	{ ...props }
	/>
	);

Editor: Add extensibility to PreviewOptions v2 #64644

Editor: Add extensibility to PreviewOptions v2 #64644

Conversation

lezama commented Aug 20, 2024 • edited Loading

Extend Preview Dropdown with Plugin API

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Future Considerations

github-actions bot commented Aug 20, 2024

github-actions bot commented Aug 20, 2024 • edited Loading

simison commented Aug 22, 2024

simison commented Aug 22, 2024

fabiankaegy commented Aug 27, 2024

Mamaduka Aug 28, 2024

Choose a reason for hiding this comment

gziolo Aug 28, 2024

Choose a reason for hiding this comment

Mamaduka Aug 28, 2024

Choose a reason for hiding this comment

gziolo Aug 28, 2024

Choose a reason for hiding this comment

gziolo left a comment

Choose a reason for hiding this comment

gziolo Aug 28, 2024

Choose a reason for hiding this comment

gziolo commented Aug 28, 2024

lezama commented Aug 30, 2024 • edited Loading

lezama commented Aug 30, 2024

youknowriad commented Sep 2, 2024

youknowriad commented Sep 2, 2024

youknowriad commented Sep 2, 2024

gziolo left a comment

Choose a reason for hiding this comment

mtias commented Sep 5, 2024

lezama commented Aug 20, 2024 •

edited

Loading

github-actions bot commented Aug 20, 2024 •

edited

Loading

lezama commented Aug 30, 2024 •

edited

Loading