Block API: Adding a description property to the block API

WordPress · Dec 28, 2017 · 003d533 · 003d533
1 parent 3a3c3d5
commit 003d533
Show file tree

Hide file tree

Showing 34 changed files with 150 additions and 231 deletions.
diff --git a/blocks/block-description/index.js b/blocks/block-description/index.js
@@ -1,12 +1,27 @@
+/**
+ * WordPress dependencies
+ */
+import { Component } from '@wordpress/element';
 /**
  * Internal dependencies
  */
 import './style.scss';
 
-export default function BlockDescription( { children } ) {
-	return (
-		<div className="components-block-description">
-			{ children }
-		</div>
-	);
+class BlockDescription extends Component {
+	constructor() {
+		super( ...arguments );
+		// eslint-disable-next-line no-console
+		console.warn( 'The wp.blocks.BlockDescription component is deprecated. Use the "description" block property instead.' );
+	}
+
+	render() {
+		const { children } = this.props;
+		return (
+			<div className="components-block-description">
+				{ children }
+			</div>
+		);
+	}
 }
+
+export default BlockDescription;
diff --git a/blocks/block-description/test/index.js b/blocks/block-description/test/index.js
@@ -8,13 +8,21 @@ import { shallow } from 'enzyme';
  */
 import BlockDescription from '../';
 
+/* eslint-disable no-console */
+function expectWarning() {
+	expect( console.warn ).toHaveBeenCalled();
+	console.warn.mockClear();
+}
+/* eslint-enable no-console */
+
 describe( 'BlockDescription', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render a <p> element with some content', () => {
 			const blockDescription = shallow( <BlockDescription><p>Hello World</p></BlockDescription> );
 			expect( blockDescription.hasClass( 'components-block-description' ) ).toBe( true );
 			expect( blockDescription.type() ).toBe( 'div' );
 			expect( blockDescription.text() ).toBe( 'Hello World' );
+			expectWarning();
 		} );
 	} );
 } );
diff --git a/blocks/library/audio/index.js b/blocks/library/audio/index.js
@@ -18,12 +18,12 @@ import MediaUploadButton from '../../media-upload-button';
 import Editable from '../../editable';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
-import InspectorControls from '../../inspector-controls';
-import BlockDescription from '../../block-description';
 
 registerBlockType( 'core/audio', {
 	title: __( 'Audio' ),
 
+	description: __( 'The Audio block allows you to embed audio files and play them back using a simple player.' ),
+
 	icon: 'format-audio',
 
 	category: 'common',
@@ -88,7 +88,7 @@ registerBlockType( 'core/audio', {
 				}
 				return false;
 			};
-			const controls = focus && [
+			const controls = focus && (
 				<BlockControls key="controls">
 					<BlockAlignmentToolbar
 						value={ align }
@@ -104,14 +104,8 @@ registerBlockType( 'core/audio', {
 							<Dashicon icon="edit" />
 						</Button>
 					</Toolbar>
-				</BlockControls>,
-
-				<InspectorControls key="inspector">
-					<BlockDescription>
-						<p>{ __( 'The Audio block allows you to embed audio files and play them back using a simple player.' ) }</p>
-					</BlockDescription>
-				</InspectorControls>,
-			];
+				</BlockControls>
+			);
 
 			const focusCaption = ( focusValue ) => setFocus( { editable: 'caption', ...focusValue } );
 

diff --git a/blocks/library/button/index.js b/blocks/library/button/index.js
@@ -19,7 +19,6 @@ import BlockAlignmentToolbar from '../../block-alignment-toolbar';
 import ColorPalette from '../../color-palette';
 import ContrastChecker from '../../contrast-checker';
 import InspectorControls from '../../inspector-controls';
-import BlockDescription from '../../block-description';
 
 const { getComputedStyle } = window;
 
@@ -99,10 +98,6 @@ class ButtonBlock extends Component {
 				/>
 				{ focus &&
 					<InspectorControls key="inspector">
-						<BlockDescription>
-							<p>{ __( 'A nice little button. Call something out with it.' ) }</p>
-						</BlockDescription>
-
 						<ToggleControl
 							label={ __( 'Stand on a line' ) }
 							checked={ !! clear }
@@ -149,6 +144,8 @@ class ButtonBlock extends Component {
 registerBlockType( 'core/button', {
 	title: __( 'Button' ),
 
+	description: __( 'A nice little button. Call something out with it.' ),
+
 	icon: 'button',
 
 	category: 'layout',

diff --git a/blocks/library/categories/block.js b/blocks/library/categories/block.js
@@ -13,7 +13,6 @@ import './editor.scss';
 import './style.scss';
 import InspectorControls from '../../inspector-controls';
 import ToggleControl from '../../inspector-controls/toggle-control';
-import BlockDescription from '../../block-description';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
 
@@ -175,9 +174,6 @@ class CategoriesBlock extends Component {
 			),
 			focus && (
 				<InspectorControls key="inspector">
-					<BlockDescription>
-						<p>{ __( 'Shows a list of your site\'s categories.' ) }</p>
-					</BlockDescription>
 					<h3>{ __( 'Categories Settings' ) }</h3>
 					<ToggleControl
 						label={ __( 'Display as dropdown' ) }

diff --git a/blocks/library/categories/index.js b/blocks/library/categories/index.js
@@ -14,6 +14,8 @@ import CategoriesBlock from './block';
 registerBlockType( 'core/categories', {
 	title: __( 'Categories' ),
 
+	description: __( 'Shows a list of your site\'s categories.' ),
+
 	icon: 'list-view',
 
 	category: 'widgets',

diff --git a/blocks/library/code/index.js b/blocks/library/code/index.js
@@ -13,12 +13,12 @@ import { __ } from '@wordpress/i18n';
  */
 import './editor.scss';
 import { registerBlockType, createBlock } from '../../api';
-import InspectorControls from '../../inspector-controls';
-import BlockDescription from '../../block-description';
 
 registerBlockType( 'core/code', {
 	title: __( 'Code' ),
 
+	description: __( 'The code block maintains spaces and tabs, great for showing code snippets.' ),
+
 	icon: 'editor-code',
 
 	category: 'formatting',
@@ -55,24 +55,17 @@ registerBlockType( 'core/code', {
 		],
 	},
 
-	edit( { attributes, setAttributes, focus, className } ) {
-		return [
-			focus && (
-				<InspectorControls key="inspector">
-					<BlockDescription>
-						<p>{ __( 'The code block maintains spaces and tabs, great for showing code snippets.' ) }</p>
-					</BlockDescription>
-				</InspectorControls>
-			),
-			<div className={ className } key="block">
+	edit( { attributes, setAttributes, className } ) {
+		return (
+			<div className={ className }>
 				<TextareaAutosize
 					value={ attributes.content }
 					onChange={ ( event ) => setAttributes( { content: event.target.value } ) }
 					placeholder={ __( 'Write code…' ) }
 					aria-label={ __( 'Code' ) }
 				/>
-			</div>,
-		];
+			</div>
+		);
 	},
 
 	save( { attributes } ) {

diff --git a/blocks/library/cover-image/index.js b/blocks/library/cover-image/index.js
@@ -19,13 +19,14 @@ import BlockAlignmentToolbar from '../../block-alignment-toolbar';
 import InspectorControls from '../../inspector-controls';
 import ToggleControl from '../../inspector-controls/toggle-control';
 import RangeControl from '../../inspector-controls/range-control';
-import BlockDescription from '../../block-description';
 
 const validAlignments = [ 'left', 'center', 'right', 'wide', 'full' ];
 
 registerBlockType( 'core/cover-image', {
 	title: __( 'Cover Image' ),
 
+	description: __( 'Cover Image is a bold image block with an optional title.' ),
+
 	icon: 'format-image',
 
 	category: 'common',
@@ -124,9 +125,6 @@ registerBlockType( 'core/cover-image', {
 				</Toolbar>
 			</BlockControls>,
 			<InspectorControls key="inspector">
-				<BlockDescription>
-					<p>{ __( 'Cover Image is a bold image block with an optional title.' ) }</p>
-				</BlockDescription>
 				<h2>{ __( 'Cover Image Settings' ) }</h2>
 				<ToggleControl
 					label={ __( 'Fixed Background' ) }

diff --git a/blocks/library/embed/index.js b/blocks/library/embed/index.js
@@ -21,8 +21,6 @@ import { registerBlockType, createBlock } from '../../api';
 import Editable from '../../editable';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
-import InspectorControls from '../../inspector-controls';
-import BlockDescription from '../../block-description';
 
 // These embeds do not work in sandboxes
 const HOSTS_NO_PREVIEWS = [ 'facebook.com' ];
@@ -31,6 +29,8 @@ function getEmbedBlockSettings( { title, icon, category = 'embed', transforms, k
 	return {
 		title,
 
+		description: __( 'The Embed block allows you to easily add videos, images, tweets, audio, and other content to your post or page.' ),
+
 		icon,
 
 		category,
@@ -134,23 +134,14 @@ function getEmbedBlockSettings( { title, icon, category = 'embed', transforms, k
 				const { setAttributes, focus, setFocus } = this.props;
 				const updateAlignment = ( nextAlign ) => setAttributes( { align: nextAlign } );
 
-				const controls = [
-					focus && (
-						<BlockControls key="controls">
-							<BlockAlignmentToolbar
-								value={ align }
-								onChange={ updateAlignment }
-							/>
-						</BlockControls>
-					),
-					focus && (
-						<InspectorControls key="inspector">
-							<BlockDescription>
-								<p>{ __( 'The Embed block allows you to easily add videos, images, tweets, audio, and other content to your post or page.' ) }</p>
-							</BlockDescription>
-						</InspectorControls>
-					),
-				];
+				const controls = focus && (
+					<BlockControls key="controls">
+						<BlockAlignmentToolbar
+							value={ align }
+							onChange={ updateAlignment }
+						/>
+					</BlockControls>
+				);
 
 				if ( fetching ) {
 					return [

diff --git a/blocks/library/freeform/index.js b/blocks/library/freeform/index.js
@@ -13,6 +13,8 @@ import OldEditor from './old-editor';
 registerBlockType( 'core/freeform', {
 	title: __( 'Classic' ),
 
+	desription: __( 'The classic editor, in block form.' ),
+
 	icon: 'editor-kitchensink',
 
 	category: 'formatting',

diff --git a/blocks/library/freeform/old-editor.js b/blocks/library/freeform/old-editor.js
@@ -10,12 +10,6 @@ import { Component } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { keycodes } from '@wordpress/utils';
 
-/**
- * Internal dependencies
- */
-import InspectorControls from '../../inspector-controls';
-import BlockDescription from '../../block-description';
-
 const { BACKSPACE, DELETE } = keycodes;
 
 function isTmceEmpty( editor ) {
@@ -185,13 +179,6 @@ export default class OldEditor extends Component {
 		const { focus, id, className } = this.props;
 
 		return [
-			focus && (
-				<InspectorControls key="inspector">
-					<BlockDescription>
-						<p>{ __( 'The classic editor, in block form.' ) }</p>
-					</BlockDescription>
-				</InspectorControls>
-			),
 			<div
 				key="toolbar"
 				id={ id + '-toolbar' }

diff --git a/blocks/library/gallery/block.js b/blocks/library/gallery/block.js
@@ -22,7 +22,6 @@ import SelectControl from '../../inspector-controls/select-control';
 import BlockControls from '../../block-controls';
 import BlockAlignmentToolbar from '../../block-alignment-toolbar';
 import GalleryImage from './gallery-image';
-import BlockDescription from '../../block-description';
 
 const isGallery = true;
 const MAX_COLUMNS = 8;
@@ -132,22 +131,6 @@ class GalleryBlock extends Component {
 		const { attributes, focus, className } = this.props;
 		const { images, columns = defaultColumnsNumber( attributes ), align, imageCrop, linkTo } = attributes;
 
-		const blockDescription = (
-			<BlockDescription>
-				<p>
-					{__( 'Image galleries are a great way to share groups of pictures on your site.' )}
-				</p>
-			</BlockDescription>
-		);
-
-		const inspectorControls = (
-			focus && (
-				<InspectorControls key="inspector">
-					{blockDescription}
-				</InspectorControls>
-			)
-		);
-
 		const dropZone = (
 			<DropZone
 				onFilesDrop={ this.dropFiles }
@@ -187,7 +170,6 @@ class GalleryBlock extends Component {
 
 			return [
 				controls,
-				inspectorControls,
 				<Placeholder
 					key="placeholder"
 					instructions={ __( 'Drag images here or insert from media library' ) }
@@ -221,7 +203,6 @@ class GalleryBlock extends Component {
 			controls,
 			focus && (
 				<InspectorControls key="inspector">
-					{blockDescription}
 					<h2>{ __( 'Gallery Settings' ) }</h2>
 					{ images.length > 1 && <RangeControl
 						label={ __( 'Columns' ) }

diff --git a/blocks/library/gallery/index.js b/blocks/library/gallery/index.js
@@ -19,6 +19,7 @@ import { default as GalleryBlock, defaultColumnsNumber } from './block';
 
 registerBlockType( 'core/gallery', {
 	title: __( 'Gallery' ),
+	description: __( 'Image galleries are a great way to share groups of pictures on your site.' ),
 	icon: 'format-gallery',
 	category: 'common',
 	keywords: [ __( 'images' ), __( 'photos' ) ],

diff --git a/blocks/library/heading/index.js b/blocks/library/heading/index.js
@@ -14,11 +14,12 @@ import Editable from '../../editable';
 import BlockControls from '../../block-controls';
 import InspectorControls from '../../inspector-controls';
 import AlignmentToolbar from '../../alignment-toolbar';
-import BlockDescription from '../../block-description';
 
 registerBlockType( 'core/heading', {
 	title: __( 'Heading' ),
 
+	description: __( 'Search engines use the headings to index the structure and content of your web pages.' ),
+
 	icon: 'heading',
 
 	category: 'common',
@@ -118,9 +119,6 @@ registerBlockType( 'core/heading', {
 			),
 			focus && (
 				<InspectorControls key="inspector">
-					<BlockDescription>
-						<p>{ __( 'Search engines use the headings to index the structure and content of your web pages.' ) }</p>
-					</BlockDescription>
 					<h3>{ __( 'Heading Settings' ) }</h3>
 					<p>{ __( 'Size' ) }</p>
 					<Toolbar