Create settings object for inner block param

WordPress · Aug 12, 2020 · 64a40e8 · 64a40e8
1 parent ce31556
commit 64a40e8
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 32 deletions.
diff --git 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
@@ -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
@@ -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,27 +204,24 @@ 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
  * given clientID. This way, the selector only refreshes on changes to blocks
  * 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 ) =>