From 21015b74302623f991040eb9fd65e1db6c7af35a Mon Sep 17 00:00:00 2001 From: Ryan Welcher Date: Mon, 26 Aug 2024 13:26:11 -0400 Subject: [PATCH 1/3] Add a conditionally rendering section to slotfill docs. --- docs/reference-guides/slotfills/README.md | 233 ++++++++++++++++++++++ 1 file changed, 233 insertions(+) diff --git a/docs/reference-guides/slotfills/README.md b/docs/reference-guides/slotfills/README.md index b09aa5d49102e..abcbd8b162a11 100644 --- a/docs/reference-guides/slotfills/README.md +++ b/docs/reference-guides/slotfills/README.md @@ -29,6 +29,239 @@ const PluginPostStatusInfoTest = () => ( registerPlugin( 'post-status-info-test', { render: PluginPostStatusInfoTest } ); ``` +## Conditionally rendering SlotFill content + +With the exception of [MainDashboardButton](/docs/reference-guides/slotfills/main-dashboard-button.md), every available SlotFill is exposed on both the post edit and site edit screens and any Fill that is registered will be rendered in both contexts. There are a number of approaches that can be implemented to conditionally render Fills. + +### Restricting fills to the edit post screen. + +A fill can be restricted to the edit post screen by checking to see if the current post type object property viewable is set to `true`. Any post type not set to viewable, does not have an associated edit post screen and is a good indicator that the user is not in the edit post screen. The example below will render its content on the edit post screen for any registered post type. + +```js +/** + * WordPress dependencies + */ +import { registerPlugin } from '@wordpress/plugins'; +import { + PluginDocumentSettingPanel, + store as editorStore, +} from '@wordpress/editor'; +import { store as coreStore } from '@wordpress/core-data'; +import { useSelect } from '@wordpress/data'; +import { __ } from '@wordpress/i18n'; + +/** + * The component to be rendered as part of the plugin. + */ +const EditPostDocumentSettingPanel = () => { + // Retrieve information about the current post type. + const isViewable = useSelect( ( select ) => { + const postTypeName = select( editorStore ).getCurrentPostType(); + const postTypeObject = select( coreStore ).getPostType( postTypeName ); + return postTypeObject?.viewable; + }, [] ); + + // If the post type is not viewable, then do not render my the fill. + if ( ! isViewable ) { + return null; + } + + return ( + +

{ __( 'Only appears in the Edit Post screen' ) }

+ + ); +}; + +registerPlugin( 'example-post-edit-only', { + render: EditPostDocumentSettingPanel, +} ); +``` + +### Restricting fills to certain post types. + +The following example expands on the example above by creating an allow list of post types where the fill should be rendered. In this case, the fill is only rendered when editing pages. + +```js +/** + * WordPress dependencies + */ +import { registerPlugin } from '@wordpress/plugins'; +import { + PluginDocumentSettingPanel, + store as editorStore, +} from '@wordpress/editor'; +import { store as coreStore } from '@wordpress/core-data'; +import { useSelect } from '@wordpress/data'; +import { __, sprintf } from '@wordpress/i18n'; + +/** + * The component to be rendered as part of the plugin. + */ +const RestrictPostTypes = () => { + // Retrieve information about the current post type. + const { isViewable, postTypeName } = useSelect( ( select ) => { + const postType = select( editorStore ).getCurrentPostType(); + const postTypeObject = select( coreStore ).getPostType( postType ); + return { + isViewable: postTypeObject?.viewable, + postTypeName: postType, + }; + }, [] ); + + // The list of post types that are allowed to render the plugin. + const allowedPostTypes = [ 'page' ]; + + // If the post type is not viewable or not in the allowed list, do not render the plugin. + if ( ! isViewable || ! allowedPostTypes.includes( postTypeName ) ) { + return null; + } + + return ( + +

+ { sprintf( + __( + 'Only appears on Post Types that are in the allowed list. %s' + ), + allowedPostTypes.join( ', ' ) + ) } +

+ + ); +}; + +registerPlugin( 'example-restrict-post-types', { + render: RestrictPostTypes, +} ); +``` + +### Restricting fills to the Side editor. + +To restrict fills to the Site editor, the reverse logic is true. If the post type object’s viewable property is set to true, then the fill should not be rendered. The example below will render its content on any Site editor screen. + +```js +/** + * WordPress dependencies + */ +import { registerPlugin } from '@wordpress/plugins'; +import { + PluginDocumentSettingPanel, + store as editorStore, +} from '@wordpress/editor'; +import { store as coreStore } from '@wordpress/core-data'; +import { useSelect } from '@wordpress/data'; +import { __ } from '@wordpress/i18n'; + +/** + * The component to be rendered as part of the plugin. + */ +const SiteEditorDocumentSettingPanel = () => { + // Retrieve information about the current post type. + const { isViewable } = useSelect( ( select ) => { + const postTypeName = select( editorStore ).getCurrentPostType(); + const postTypeObject = select( coreStore ).getPostType( postTypeName ); + + // A viewable post type is one than can be viewed in the WordPress admin. Internal ones are not set to viewable. + return postTypeObject?.viewable; + }, [] ); + + // If the post type is viewable, do not render my fill + if ( isViewable ) { + return null; + } + + return ( + +

{ __( 'Only appears in the Site Editor' ) }

+ + ); +}; + +registerPlugin( 'example-site-editor', { + render: SiteEditorDocumentSettingPanel, +} ); +``` + +### Restricting fills to certain screens in the Site editor. + +This example builds on the example above by providing an allow list to control which screens a fill can be rendered within the Site editor. + +```js +/** + * WordPress dependencies + */ +import { registerPlugin } from '@wordpress/plugins'; +import { + PluginDocumentSettingPanel, + store as editorStore, +} from '@wordpress/editor'; +import { store as coreStore } from '@wordpress/core-data'; +import { useSelect } from '@wordpress/data'; +import { __, sprintf } from '@wordpress/i18n'; + +/** + * The component to be rendered as part of the plugin. + */ +const SiteEditorDocumentSettingPanel = () => { + // Allowed areas in the Site Editor. + const allowedSiteEditorScreens = [ + 'wp_template', // Templates + 'wp_block', // Patterns + 'wp_template_part', // Template Parts + ]; + + const { isViewable, postType } = useSelect( ( select ) => { + const postTypeName = select( editorStore ).getCurrentPostType(); + const postTypeObject = select( coreStore ).getPostType( postTypeName ); + + return { + // A viewable post type is one than can be viewed in the WordPress admin. Internal ones are not set to viewable. + isViewable: postTypeObject?.viewable, + postType: postTypeName, + }; + }, [] ); + + // If the post type is viewable, do not render my plugin. + if ( isViewable || ! allowedSiteEditorScreens.includes( postType ) ) { + return null; + } + + return ( + +

+ { sprintf( + __( + 'Only appears on Editor Screens that are in the allowed list. %s' + ), + allowedSiteEditorScreens.join( ', ' ) + ) } +

+ + ); +}; + +registerPlugin( 'example-site-editor-only', { + render: SiteEditorDocumentSettingPanel, +} ); +``` + ## How do they work? SlotFills are created using `createSlotFill`. This creates two components, `Slot` and `Fill` which are then used to create a new component that is exported on the `wp.plugins` global. From 7d89b0f99b1e5bd7d95fb87cb22a1f58b41fbd2e Mon Sep 17 00:00:00 2001 From: Ryan Welcher Date: Mon, 26 Aug 2024 14:01:49 -0400 Subject: [PATCH 2/3] Changes per peer review. --- docs/reference-guides/slotfills/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/reference-guides/slotfills/README.md b/docs/reference-guides/slotfills/README.md index abcbd8b162a11..6af08d8eed15c 100644 --- a/docs/reference-guides/slotfills/README.md +++ b/docs/reference-guides/slotfills/README.md @@ -31,11 +31,11 @@ registerPlugin( 'post-status-info-test', { render: PluginPostStatusInfoTest } ); ## Conditionally rendering SlotFill content -With the exception of [MainDashboardButton](/docs/reference-guides/slotfills/main-dashboard-button.md), every available SlotFill is exposed on both the post edit and site edit screens and any Fill that is registered will be rendered in both contexts. There are a number of approaches that can be implemented to conditionally render Fills. +With the exception of [MainDashboardButton](/docs/reference-guides/slotfills/main-dashboard-button.md), every available SlotFill is exposed in both the Post Editor and Site Editor and any Fill that is registered will be rendered in both contexts. There are a number of approaches that can be implemented to conditionally render Fills. -### Restricting fills to the edit post screen. +### Restricting fills to the Post Editor -A fill can be restricted to the edit post screen by checking to see if the current post type object property viewable is set to `true`. Any post type not set to viewable, does not have an associated edit post screen and is a good indicator that the user is not in the edit post screen. The example below will render its content on the edit post screen for any registered post type. +A fill can be restricted to the Post Editor by checking to see if the current post type object property `viewable` is set to `true`. Any post type not set to `viewable`, does not have an associated edit post screen and is a good indicator that the user is not in the Post Editor. The example below will render its content on the edit post screen for any registered post type. ```js /** @@ -144,9 +144,9 @@ registerPlugin( 'example-restrict-post-types', { } ); ``` -### Restricting fills to the Side editor. +### Restricting fills to the Side Editor -To restrict fills to the Site editor, the reverse logic is true. If the post type object’s viewable property is set to true, then the fill should not be rendered. The example below will render its content on any Site editor screen. +To restrict fills to the Site Editor, the reverse logic is true. If the post type object’s `viewable` property is set to `true`, then the fill should not be rendered. The example below will render its content on any Site Editor screen. ```js /** @@ -195,9 +195,9 @@ registerPlugin( 'example-site-editor', { } ); ``` -### Restricting fills to certain screens in the Site editor. +### Restricting fills to certain screens in the Site Editor. -This example builds on the example above by providing an allow list to control which screens a fill can be rendered within the Site editor. +This example builds on the example above by providing an allow list to control which screens a fill can be rendered within the Site Editor. ```js /** From 25639bc02e3f51045b5056494cf06a444a2cbdca Mon Sep 17 00:00:00 2001 From: Ryan Welcher Date: Mon, 26 Aug 2024 14:16:30 -0400 Subject: [PATCH 3/3] Update docs/reference-guides/slotfills/README.md Co-authored-by: Nick Diego --- docs/reference-guides/slotfills/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/slotfills/README.md b/docs/reference-guides/slotfills/README.md index 6af08d8eed15c..bab08dc34c40c 100644 --- a/docs/reference-guides/slotfills/README.md +++ b/docs/reference-guides/slotfills/README.md @@ -146,7 +146,7 @@ registerPlugin( 'example-restrict-post-types', { ### Restricting fills to the Side Editor -To restrict fills to the Site Editor, the reverse logic is true. If the post type object’s `viewable` property is set to `true`, then the fill should not be rendered. The example below will render its content on any Site Editor screen. +To restrict fills to the Site Editor, the reverse logic is true. If the post type object's `viewable` property is set to `true`, then the fill should not be rendered. The example below will render its content on any Site Editor screen. ```js /**