Framework: Deprecate grouped inner blocks layouts (#7841)

WordPress · Jul 20, 2018 · 6cee18e · 6cee18e
1 parent a1bb351
commit 6cee18e
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 85 deletions.
diff --git a/docs/reference/deprecated.md b/docs/reference/deprecated.md
@@ -16,12 +16,13 @@ Gutenberg's deprecation policy is intended to support backwards-compatibility fo
  - The `wp.editor.MediaPlaceholder` component `onSelectUrl` prop has been renamed to `onSelectURL`.
  - The `wp.editor.UrlInput` component has been renamed to `wp.editor.URLInput`.
  - The Text Columns block has been removed. Please use the Columns block instead.
+ - `InnerBlocks` grouped layout is removed. Use intermediary nested inner blocks instead. See Columns / Column block for reference implementation.
 
 ## 3.4.0
 
  - `focusOnMount` prop in the `Popover` component has been changed from `Boolean`-only to an enum-style property that accepts `"firstElement"`, `"container"`, or `false`. Please convert any `<Popover focusOnMount />` usage to `<Popover focusOnMount="firstElement" />`.
  - `wp.utils.keycodes` utilities are removed. Please use `wp.keycodes` instead.
- -  Block `id` prop in `edit` function removed. Please use block `clientId` prop instead.
+ - Block `id` prop in `edit` function removed. Please use block `clientId` prop instead.
 
 ## 3.3.0
 

diff --git a/editor/components/block-list/index.js b/editor/components/block-list/index.js
@@ -12,6 +12,7 @@ import {
  */
 import { createElement } from '@wordpress/element';
 import { withSelect } from '@wordpress/data';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -34,6 +35,13 @@ const GroupedLayoutBlockList = withSelect(
 	layouts,
 	...props
 } ) => map( layouts, ( layout ) => {
+	deprecated( 'grouped layout', {
+		alternative: 'intermediary nested inner blocks',
+		version: '3.5',
+		plugin: 'Gutenberg',
+		hint: 'See core Columns / Column block for reference implementation',
+	} );
+
 	// Filter blocks assigned to layout when rendering grouped layouts.
 	const layoutBlockClientIds = reduce( blocks, ( result, block ) => {
 		if ( get( block, [ 'attributes', 'layout' ] ) === layout.name ) {

diff --git a/editor/components/inner-blocks/README.md b/editor/components/inner-blocks/README.md
@@ -107,101 +107,21 @@ If the block is a top level block: the locking of the Custom Post Type is used.
 ### `layouts`
 * **Type:** `Array<Object>|Object`
 
-To achieve distinct arrangements of nested blocks, you may assign layout as an array of objects, or an object. When assigned, a user will be provided with the option to move blocks between layouts, and the rendered output will assign a layout-specific class which can be used in your block stylesheet to effect the visual arrangement of nested blocks.
+To achieve distinct arrangements of nested blocks, you may assign layout as an object. When assigned, the rendered output will assign a layout-specific class which can be used in your block stylesheet to effect the visual arrangement of nested blocks.
 
-Because `InnerBlocks.Content` will generate a single continuous flow of block markup for nested content, it may be advisable to use [CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout) to assign layout positions. Be aware that CSS grid is [not supported in legacy browsers](https://caniuse.com/#feat=css-grid), and therefore you should consider how this might impact your block's appearance when viewed on the front end of a site in such browsers.
+A layout is an object where each key is the `slug` of the layout and its value an object consisting of:
 
-Layouts can be assigned either as an object (ungrouped layouts) or an array of objects (grouped layouts). These are documented below.
-
-In both cases, each layout consists of:
-
-- Name: A slug to use in generating the layout class applied to nested blocks
 - Icon (`icon: string`): The slug of the Dashicon to use in controls presented to the user in moving between layouts
    - Reference: https://developer.wordpress.org/resource/dashicons/
 - Label (`label: string`): The text to display in the controls presented to the user in moving between layouts
 
-_Ungrouped Layouts:_
+The `slug` is also used to create the class name for the block. A slug of `normal` would output the class `"layout-normal"`.
 
-If you do not depend on a particular order of markup for your nested content and need merely to assign a layout class to each nested block, you should assign `layouts` as an object, where each key is the name of a layout:
+**Example:**
 
 ```jsx
 <InnerBlocks layouts={ {
 	normal: { label: 'Normal Width', icon: 'align-center' },
 	wide: { label: 'Width Width', icon: 'align-wide' },
 } } />
 ```
-
-_Grouped Layouts:_
-
-If your nested content depends on having each layout grouped in its markup, you should assign `layouts` as an array of layout objects, where the name of the layout is set as a property of the object:
-
-```jsx
-<InnerBlocks layouts={ [
-	{ name: 'column-1', label: 'Column 1', icon: 'columns' },
-	{ name: 'column-2', label: 'Column 2', icon: 'columns' },
-] } />
-```
-
-Consider a Columns block. When the user changes the layout of a block from one column to another, it is not sufficient to simply reassign the class name of the block to the new layout, as the user may then proceed to attempt to move the block up or down within the new column. The expected behavior here requires that the markup of the block itself be moved in relation to blocks already present in the new layout.
-
-```html
-<!-- wp:columns -->
-<div class="wp-block-columns">
-	<!-- wp:paragraph {"layout":"column-1"} -->
-	<p>First Paragraph</p>
-	<!-- /wp:paragraph -->
-
-	<!-- wp:paragraph {"layout":"column-1"} -->
-	<p>Second Paragraph</p>
-	<!-- /wp:paragraph -->
-
-	<!-- wp:paragraph {"layout":"column-2"} -->
-	<p>Third Paragraph</p>
-	<!-- /wp:paragraph -->
-</div>
-<!-- /wp:columns -->
-```
-
-In the above example markup, if the user moved the first nested paragraph block to the second column, we must ensure that if they then proceed to move the block down, that the block would be the last item in the markup, otherwise it would not appear to move because it would still exist in markup prior to the third paragraph.
-
-_Bad:_
-
-```html
-<!-- wp:columns -->
-<div class="wp-block-columns">
-	<!-- wp:paragraph {"layout":"column-2"} -->
-	<p>First Paragraph</p>
-	<!-- /wp:paragraph -->
-
-	<!-- wp:paragraph {"layout":"column-1"} -->
-	<p>Second Paragraph</p>
-	<!-- /wp:paragraph -->
-
-	<!-- wp:paragraph {"layout":"column-2"} -->
-	<p>Third Paragraph</p>
-	<!-- /wp:paragraph -->
-</div>
-<!-- /wp:columns -->
-```
-
-We achieve this by ensuring that the markup of each layout is kept grouped together.
-
-_Good:_
-
-```html
-<!-- wp:columns -->
-<div class="wp-block-columns">
-	<!-- wp:paragraph {"layout":"column-1"} -->
-	<p>Second Paragraph</p>
-	<!-- /wp:paragraph -->
-
-	<!-- wp:paragraph {"layout":"column-2"} -->
-	<p>First Paragraph</p>
-	<!-- /wp:paragraph -->
-
-	<!-- wp:paragraph {"layout":"column-2"} -->
-	<p>Third Paragraph</p>
-	<!-- /wp:paragraph -->
-</div>
-<!-- /wp:columns -->
-```