From 003d5337075a05db23bb0c151d67132921c79473 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Mon, 25 Dec 2017 12:31:13 +0100 Subject: [PATCH] Block API: Adding a description property to the block API --- blocks/block-description/index.js | 27 ++++++++++++++---- blocks/block-description/test/index.js | 8 ++++++ blocks/library/audio/index.js | 16 ++++------- blocks/library/button/index.js | 7 ++--- blocks/library/categories/block.js | 4 --- blocks/library/categories/index.js | 2 ++ blocks/library/code/index.js | 21 +++++--------- blocks/library/cover-image/index.js | 6 ++-- blocks/library/embed/index.js | 29 +++++++------------ blocks/library/freeform/index.js | 2 ++ blocks/library/freeform/old-editor.js | 13 --------- blocks/library/gallery/block.js | 19 ------------- blocks/library/gallery/index.js | 1 + blocks/library/heading/index.js | 6 ++-- blocks/library/html/index.js | 11 ++----- blocks/library/image/block.js | 13 --------- blocks/library/image/index.js | 2 ++ blocks/library/latest-posts/block.js | 4 --- blocks/library/latest-posts/index.js | 2 ++ blocks/library/list/index.js | 11 +------ blocks/library/more/index.js | 6 ++-- blocks/library/paragraph/index.js | 6 ++-- blocks/library/preformatted/index.js | 11 ++----- blocks/library/pullquote/index.js | 11 ++----- blocks/library/quote/index.js | 10 +------ blocks/library/separator/index.js | 17 +++-------- blocks/library/shortcode/index.js | 14 ++------- blocks/library/table/index.js | 10 +------ blocks/library/text-columns/index.js | 6 ++-- blocks/library/verse/index.js | 18 ++++-------- blocks/library/video/index.js | 10 ++----- docs/block-api.md | 10 +++++++ editor/components/block-inspector/index.js | 18 ++++++++++-- editor/components/block-inspector/style.scss | 30 ++++++++++++++++++++ 34 files changed, 150 insertions(+), 231 deletions(-) diff --git a/blocks/block-description/index.js b/blocks/block-description/index.js index cdf5749bff607d..5b56fe9a0a2b0a 100644 --- 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 ( -
- { children } -
- ); +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 ( +
+ { children } +
+ ); + } } + +export default BlockDescription; diff --git a/blocks/block-description/test/index.js b/blocks/block-description/test/index.js index 5273d27608ba6a..eaf08091a66925 100644 --- a/blocks/block-description/test/index.js +++ b/blocks/block-description/test/index.js @@ -8,6 +8,13 @@ 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

element with some content', () => { @@ -15,6 +22,7 @@ describe( '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 index d8d7587a76d6b7..d8843c41e907d8 100644 --- 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 && ( - , - - - -

{ __( 'The Audio block allows you to embed audio files and play them back using a simple player.' ) }

- - , - ]; + + ); const focusCaption = ( focusValue ) => setFocus( { editable: 'caption', ...focusValue } ); diff --git a/blocks/library/button/index.js b/blocks/library/button/index.js index 46fdf9c1b543dd..b51b9eb47c1e68 100644 --- 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 && - -

{ __( 'A nice little button. Call something out with it.' ) }

- - - -

{ __( 'Shows a list of your site\'s categories.' ) }

-

{ __( 'Categories Settings' ) }

- -

{ __( 'The code block maintains spaces and tabs, great for showing code snippets.' ) }

- - - ), -
+ edit( { attributes, setAttributes, className } ) { + return ( +
setAttributes( { content: event.target.value } ) } placeholder={ __( 'Write code…' ) } aria-label={ __( 'Code' ) } /> -
, - ]; +
+ ); }, save( { attributes } ) { diff --git a/blocks/library/cover-image/index.js b/blocks/library/cover-image/index.js index 3d45120bc37e9d..2ef311ec9f9d81 100644 --- 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', { , - -

{ __( 'Cover Image is a bold image block with an optional title.' ) }

-

{ __( 'Cover Image Settings' ) }

setAttributes( { align: nextAlign } ); - const controls = [ - focus && ( - - - - ), - focus && ( - - -

{ __( 'The Embed block allows you to easily add videos, images, tweets, audio, and other content to your post or page.' ) }

- - - ), - ]; + const controls = focus && ( + + + + ); if ( fetching ) { return [ diff --git a/blocks/library/freeform/index.js b/blocks/library/freeform/index.js index ee4242f1ce93bb..b92aa4f0994a91 100644 --- 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 index e1c7204eba213f..ac4ba65529ab30 100644 --- 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 && ( - - -

{ __( 'The classic editor, in block form.' ) }

- - - ),
-

- {__( 'Image galleries are a great way to share groups of pictures on your site.' )} -

- - ); - - const inspectorControls = ( - focus && ( - - {blockDescription} - - ) - ); - const dropZone = ( - {blockDescription}

{ __( 'Gallery Settings' ) }

{ images.length > 1 && - -

{ __( 'Search engines use the headings to index the structure and content of your web pages.' ) }

-

{ __( 'Heading Settings' ) }

{ __( 'Size' ) }

setAttributes( { content: event.target.value } ) } aria-label={ __( 'HTML' ) } />, - focus && ( - - -

{ __( 'Add custom HTML code and preview it right here in the editor.' ) }

- - - ), ] ), save( { attributes } ) { diff --git a/blocks/library/image/block.js b/blocks/library/image/block.js index 850d2f34f84e5a..661621298411e7 100644 --- a/blocks/library/image/block.js +++ b/blocks/library/image/block.js @@ -36,7 +36,6 @@ import TextControl from '../../inspector-controls/text-control'; import SelectControl from '../../inspector-controls/select-control'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; -import BlockDescription from '../../block-description'; import UrlInputButton from '../../url-input/button'; import ImageSize from './image-size'; @@ -122,12 +121,6 @@ class ImageBlock extends Component { const uploadFromFiles = ( event ) => mediaUpload( event.target.files, setAttributes ); const dropFiles = ( files ) => mediaUpload( files, setAttributes ); - const blockDescription = ( - -

{ __( 'Worth a thousand words.' ) }

- - ); - const controls = ( focus && ( @@ -157,11 +150,6 @@ class ImageBlock extends Component { if ( ! url ) { return [ controls, - focus && ( - - { blockDescription } - - ), - { blockDescription }

{ __( 'Image Settings' ) }

{ ! isEmpty( availableSizes ) && ( diff --git a/blocks/library/image/index.js b/blocks/library/image/index.js index 4c94d5f26de71b..65ed77a7ab496c 100644 --- a/blocks/library/image/index.js +++ b/blocks/library/image/index.js @@ -15,6 +15,8 @@ import ImageBlock from './block'; registerBlockType( 'core/image', { title: __( 'Image' ), + description: __( 'Worth a thousand words.' ), + icon: 'format-image', category: 'common', diff --git a/blocks/library/latest-posts/block.js b/blocks/library/latest-posts/block.js index 75e4b8e22c5383..832e4647db1515 100644 --- a/blocks/library/latest-posts/block.js +++ b/blocks/library/latest-posts/block.js @@ -23,7 +23,6 @@ import QueryPanel from '../../query-panel'; import InspectorControls from '../../inspector-controls'; import ToggleControl from '../../inspector-controls/toggle-control'; import RangeControl from '../../inspector-controls/range-control'; -import BlockDescription from '../../block-description'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; @@ -50,9 +49,6 @@ class LatestPostsBlock extends Component { const inspectorControls = focus && ( - -

{ __( 'Shows a list of your site\'s most recent posts.' ) }

-

{ __( 'Latest Posts Settings' ) }

{ if ( undefined === content ) { @@ -75,6 +73,7 @@ const toBrDelimitedContent = ( values ) => { registerBlockType( 'core/list', { title: __( 'List' ), + description: __( 'List. Numbered or bulleted.' ), icon: 'editor-ul', category: 'common', keywords: [ __( 'bullet list' ), __( 'ordered list' ), __( 'numbered list' ) ], @@ -321,14 +320,6 @@ registerBlockType( 'core/list', { ] } /> ), - focus && ( - - -

{ __( 'List. Numbered or bulleted.' ) }

- -

{ __( 'No advanced options.' ) }

- - ), - -

{ __( '"More" allows you to break your post into a part shown on index pages, and the subsequent after clicking a "Read More" link.' ) }

- - -

{ __( 'This is a simple text only block for inserting a single paragraph of content.' ) }

- - -

{ __( 'Preformatted text keeps your spaces, tabs and linebreaks as they are.' ) }

- - - ), map( value, ( subValue => subValue.children ) ); const fromEditableValue = value => map( value, ( subValue ) => ( { @@ -50,6 +48,8 @@ registerBlockType( 'core/pullquote', { title: __( 'Pullquote' ), + description: __( 'A pullquote is a brief, attention-catching quotation taken from the main text of an article and used as a subheading or graphic feature.' ), + icon: 'format-quote', category: 'formatting', @@ -68,13 +68,6 @@ registerBlockType( 'core/pullquote', { const updateAlignment = ( nextAlign ) => setAttributes( { align: nextAlign } ); return [ - focus && ( - - -

{ __( 'A pullquote is a brief, attention-catching quotation taken from the main text of an article and used as a subheading or graphic feature.' ) }

- - - ), focus && ( value.map( ( subValue => subValue.children ) ); const fromEditableValue = value => value.map( ( subValue ) => ( { @@ -55,6 +53,7 @@ const blockAttributes = { registerBlockType( 'core/quote', { title: __( 'Quote' ), + description: __( 'Quote. In quoting others, we cite ourselves. (Julio Cortázar)' ), icon: 'format-quote', category: 'common', @@ -176,13 +175,6 @@ registerBlockType( 'core/quote', { /> ), - focus && ( - - -

{ __( 'Quote. In quoting others, we cite ourselves. (Julio Cortázar)' ) }

- - - ),
- -

{ __( 'Use the separator to indicate a thematic change in the content.' ) }

- - - ), -
, - ]; + edit( { className } ) { + return
; }, save() { diff --git a/blocks/library/shortcode/index.js b/blocks/library/shortcode/index.js index abbc63af1bbb6b..e208f26482138c 100644 --- a/blocks/library/shortcode/index.js +++ b/blocks/library/shortcode/index.js @@ -14,12 +14,12 @@ import { withInstanceId, Dashicon } from '@wordpress/components'; */ import './editor.scss'; import { registerBlockType } from '../../api'; -import InspectorControls from '../../inspector-controls'; -import BlockDescription from '../../block-description'; registerBlockType( 'core/shortcode', { title: __( 'Shortcode' ), + description: __( 'A shortcode is a WordPress-specific code snippet that is written between square brackets as [shortcode]. ' ), + icon: 'marker', category: 'widgets', @@ -62,7 +62,7 @@ registerBlockType( 'core/shortcode', { }, edit: withInstanceId( - ( { attributes, setAttributes, instanceId, focus } ) => { + ( { attributes, setAttributes, instanceId } ) => { const inputId = `blocks-shortcode-input-${ instanceId }`; return ( @@ -80,14 +80,6 @@ registerBlockType( 'core/shortcode', { text: event.target.value, } ) } /> - { focus && - - -

{ __( 'A shortcode is a WordPress-specific code snippet that is written between square brackets as [shortcode]. ' ) }

- -

{ __( 'No advanced options.' ) }

- - }
); } diff --git a/blocks/library/table/index.js b/blocks/library/table/index.js index 861017d695fcfa..f3ec2e2ca52bcf 100644 --- a/blocks/library/table/index.js +++ b/blocks/library/table/index.js @@ -12,11 +12,10 @@ import { registerBlockType } from '../../api'; import TableBlock from './table-block'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; -import InspectorControls from '../../inspector-controls'; -import BlockDescription from '../../block-description'; registerBlockType( 'core/table', { title: __( 'Table' ), + description: __( 'Tables. Best used for tabular data.' ), icon: 'editor-table', category: 'formatting', @@ -57,13 +56,6 @@ registerBlockType( 'core/table', { const { content } = attributes; const updateAlignment = ( nextAlign ) => setAttributes( { align: nextAlign } ); return [ - focus && ( - - -

{ __( 'Tables. Best used for tabular data.' ) }

- - - ), focus && ( - -

{ __( 'Add text across columns. This block is experimental' ) }

- - -

{ __( 'Write poetry and other literary expressions honoring all spaces and line-breaks.' ) }

- - - ), + return ( { setAttributes( { @@ -73,8 +65,8 @@ registerBlockType( 'core/verse', { placeholder={ __( 'Write…' ) } wrapperClassName={ className } formattingControls={ [ 'bold', 'italic', 'strikethrough' ] } - />, - ]; + /> + ); }, save( { attributes, className } ) { diff --git a/blocks/library/video/index.js b/blocks/library/video/index.js index 427054dbbabb0e..893e91dc297f9d 100644 --- a/blocks/library/video/index.js +++ b/blocks/library/video/index.js @@ -17,12 +17,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/video', { title: __( 'Video' ), + description: __( 'Video, locally hosted, locally sourced.' ), + icon: 'format-video', category: 'common', @@ -90,12 +90,6 @@ registerBlockType( 'core/video', { , - - - -

{ __( 'Video, locally hosted, locally sourced.' ) }

- - , ]; if ( ! src ) { diff --git a/docs/block-api.md b/docs/block-api.md index bff17655d29070..984648272d5aa6 100644 --- a/docs/block-api.md +++ b/docs/block-api.md @@ -40,6 +40,16 @@ This is the display title for your block, which can be translated with our trans title: 'Book' ``` +#### Description (optional) + +* **Type:** `String` + +This is a short description for your block, which can be translated with our translation functions. This will be shown in the block inspector. + +```js +description: 'Block showing a Book card.' +``` + #### Category * **Type:** `String [ common | formatting | layout | widgets | embed ]` diff --git a/editor/components/block-inspector/index.js b/editor/components/block-inspector/index.js index 769ec5d9c823c8..6d9b0545430776 100644 --- a/editor/components/block-inspector/index.js +++ b/editor/components/block-inspector/index.js @@ -8,6 +8,7 @@ import { connect } from 'react-redux'; */ import { __ } from '@wordpress/i18n'; import { Slot } from '@wordpress/components'; +import { getBlockType, BlockIcon } from '@wordpress/blocks'; /** * Internal Dependencies @@ -24,9 +25,20 @@ const BlockInspector = ( { selectedBlock, count } ) => { return { __( 'No block selected.' ) }; } - return ( - - ); + const blockType = getBlockType( selectedBlock.name ); + + return [ +
+
+ +
+
+
{ blockType.title }
+
{ blockType.description }
+
+
, + , + ]; }; export default connect( diff --git a/editor/components/block-inspector/style.scss b/editor/components/block-inspector/style.scss index 3c43a3293dc23f..5b582584e5444d 100644 --- a/editor/components/block-inspector/style.scss +++ b/editor/components/block-inspector/style.scss @@ -7,3 +7,33 @@ border-bottom: 1px solid $light-gray-500; text-align: center; } + + +.editor-block-inspector__card { + display: flex; + align-items: flex-start; + border-bottom: 1px solid $light-gray-500; + margin: -16px -16px 16px -16px; + padding: 16px; +} + +.editor-block-inspector__card-icon { + border: 1px solid $light-gray-700; + padding: 8px; + margin-right: 10px; + height: 36px; + width: 36px; +} + +.editor-block-inspector__card-content { + flex-grow: 1; +} + +.editor-block-inspector__card-title { + font-weight: 500; + margin-bottom: 5px; +} + +.editor-block-inspector__card-description { + font-size: 12px; +}