diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md index c8aa14e6ee9784..0010e906d05318 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -94,15 +94,15 @@ then the nested template part's child blocks will not be returned. This way, the template block itself is considered part of the parent, but the children are not. -You can override this behavior with the includeControlledInnerBlocks. So if -you call `getBlock( TP, true )`, it will return all nested blocks, including -all child inner block controllers and their children. +You can override this behavior with the includeControlledInnerBlocks setting. +So if you call `getBlock( TP, { WPGetBlockSettings: true } )`, it will return +all nested blocks, including all child inner block controllers and their children. _Parameters_ - _state_ `Object`: Editor state. - _clientId_ `string`: Block client ID. -- _includeControlledInnerBlocks_ `?boolean`: If true, include controlleld inner block subtrees. The default behavior is to exclude controlled inner blocks (false). +- _settings_ `?WPGetBlockSettings`: A settings object. _Returns_ @@ -283,7 +283,7 @@ _Returns_ Returns all block objects for the current post being edited as an array in the order they appear in the post. Note that this will exclude child blocks of nested inner block controllers unless the `includeControlledInnerBlocks` -parameter is set to true. +setting is set to true. Note: It's important to memoize this selector to avoid return a new instance on each call. We use the block cache state for each top-level block of the @@ -295,7 +295,7 @@ _Parameters_ - _state_ `Object`: Editor state. - _rootClientId_ `?string`: Optional root client ID of block list. -- _includeControlledInnerBlocks_ `?boolean`: If true, include controlleld inner block subtrees. The default behavior is to exclude controlled inner blocks (false). +- _settings_ `?WPGetBlockSettings`: A settings object. _Returns_ diff --git a/packages/block-editor/src/components/block-navigation/index.js b/packages/block-editor/src/components/block-navigation/index.js index 1fc4cbb718fc02..f704338e52824e 100644 --- a/packages/block-editor/src/components/block-navigation/index.js +++ b/packages/block-editor/src/components/block-navigation/index.js @@ -67,11 +67,11 @@ export default compose( } = select( 'core/block-editor' ); const selectedBlockClientId = getSelectedBlockClientId(); return { - rootBlocks: getBlocks( '', true ), + rootBlocks: getBlocks( '', { includeControlledInnerBlocks: true } ), rootBlock: selectedBlockClientId ? getBlock( getBlockHierarchyRootClientId( selectedBlockClientId ), - true + { includeControlledInnerBlocks: true } ) : null, selectedBlockClientId, diff --git a/packages/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index 7ceacbb6c95675..e923580b30d11f 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -40,6 +40,16 @@ import { Platform } from '@wordpress/element'; * text value. See `wp.richText.create`. */ +/** + * Settings which can be passed to the getBlock or getBlocks selectors. + * + * @typedef {Object} WPGetBlockSettings + * @property {boolean} includeControlledInnerBlocks If true, include nested child + * blocks of inner block controllers. + * The default of false excludes + * nested blocks of inner block controllers. + */ + // Module constants const MILLISECONDS_PER_HOUR = 3600 * 1000; const MILLISECONDS_PER_DAY = 24 * 3600 * 1000; @@ -133,21 +143,18 @@ export function getBlockAttributes( state, clientId ) { * the template block itself is considered part of the parent, but the children * are not. * - * You can override this behavior with the includeControlledInnerBlocks. So if - * you call `getBlock( TP, true )`, it will return all nested blocks, including - * all child inner block controllers and their children. + * You can override this behavior with the includeControlledInnerBlocks setting. + * So if you call `getBlock( TP, { WPGetBlockSettings: true } )`, it will return + * all nested blocks, including all child inner block controllers and their children. * - * @param {Object} state Editor state. - * @param {string} clientId Block client ID. - * @param {?boolean} includeControlledInnerBlocks If true, include controlleld - * inner block subtrees. The default - * behavior is to exclude controlled - * inner blocks (false). + * @param {Object} state Editor state. + * @param {string} clientId Block client ID. + * @param {?WPGetBlockSettings} settings A settings object. * * @return {Object} Parsed block object. */ export const getBlock = createSelector( - ( state, clientId, includeControlledInnerBlocks = false ) => { + ( state, clientId, { includeControlledInnerBlocks = false } = {} ) => { const block = state.blocks.byClientId[ clientId ]; if ( ! block ) { return null; @@ -160,11 +167,9 @@ export const getBlock = createSelector( ! includeControlledInnerBlocks && areInnerBlocksControlled( state, clientId ) ? EMPTY_ARRAY - : getBlocks( - state, - clientId, - includeControlledInnerBlocks - ), + : getBlocks( state, clientId, { + includeControlledInnerBlocks, + } ), }; }, ( state, clientId ) => [ @@ -199,7 +204,7 @@ export const __unstableGetBlockWithoutInnerBlocks = createSelector( * Returns all block objects for the current post being edited as an array in * the order they appear in the post. Note that this will exclude child blocks * of nested inner block controllers unless the `includeControlledInnerBlocks` - * parameter is set to true. + * setting is set to true. * * Note: It's important to memoize this selector to avoid return a new instance * on each call. We use the block cache state for each top-level block of the @@ -207,19 +212,16 @@ export const __unstableGetBlockWithoutInnerBlocks = createSelector( * associated with the given entity, and does not refresh when changes are made * to blocks which are part of different inner block controllers. * - * @param {Object} state Editor state. - * @param {?string} rootClientId Optional root client ID of block list. - * @param {?boolean} includeControlledInnerBlocks If true, include controlleld - * inner block subtrees. The default - * behavior is to exclude controlled - * inner blocks (false). + * @param {Object} state Editor state. + * @param {?string} rootClientId Optional root client ID of block list. + * @param {?WPGetBlockSettings} settings A settings object. * * @return {Object[]} Post blocks. */ export const getBlocks = createSelector( - ( state, rootClientId, includeControlledInnerBlocks = false ) => { + ( state, rootClientId, { includeControlledInnerBlocks = false } = {} ) => { return map( getBlockOrder( state, rootClientId ), ( clientId ) => - getBlock( state, clientId, includeControlledInnerBlocks ) + getBlock( state, clientId, { includeControlledInnerBlocks } ) ); }, ( state, rootClientId ) =>