diff --git a/packages/block-editor/src/components/block-styles/index.js b/packages/block-editor/src/components/block-styles/index.js index 3adc97992073..25a2fd7b235c 100644 --- a/packages/block-editor/src/components/block-styles/index.js +++ b/packages/block-editor/src/components/block-styles/index.js @@ -12,7 +12,7 @@ import { withSelect, withDispatch } from '@wordpress/data'; import TokenList from '@wordpress/token-list'; import { ENTER, SPACE } from '@wordpress/keycodes'; import { _x } from '@wordpress/i18n'; -import { getBlockType, cloneBlock, createBlock } from '@wordpress/blocks'; +import { getBlockType, cloneBlock, getBlockFromExample } from '@wordpress/blocks'; /** * Internal dependencies @@ -124,9 +124,13 @@ function BlockStyles( {
diff --git a/packages/block-editor/src/components/block-switcher/index.js b/packages/block-editor/src/components/block-switcher/index.js index 36e920d9e48c..4f3510e4ebbb 100644 --- a/packages/block-editor/src/components/block-switcher/index.js +++ b/packages/block-editor/src/components/block-switcher/index.js @@ -8,7 +8,7 @@ import { castArray, filter, first, mapKeys, orderBy, uniq, map } from 'lodash'; */ import { __, _n, sprintf } from '@wordpress/i18n'; import { Dropdown, IconButton, Toolbar, PanelBody, Path, SVG } from '@wordpress/components'; -import { getBlockType, getPossibleBlockTransformations, switchToBlockType, cloneBlock, createBlock } from '@wordpress/blocks'; +import { getBlockType, getPossibleBlockTransformations, switchToBlockType, cloneBlock, getBlockFromExample } from '@wordpress/blocks'; import { Component } from '@wordpress/element'; import { DOWN } from '@wordpress/keycodes'; import { withSelect, withDispatch } from '@wordpress/data'; @@ -171,7 +171,10 @@ export class BlockSwitcher extends Component { viewportWidth={ 500 } blocks={ hoveredBlockType.example ? - createBlock( hoveredBlock.name, { ...hoveredBlockType.example.attributes, className: hoveredClassName }, hoveredBlockType.example.innerBlocks ) : + getBlockFromExample( hoveredBlock.name, { + attributes: { ...hoveredBlockType.example.attributes, className: hoveredClassName }, + innerBlocks: hoveredBlockType.example.innerBlocks, + } ) : cloneBlock( hoveredBlock, { className: hoveredClassName } ) } /> diff --git a/packages/block-editor/src/components/inserter/menu.js b/packages/block-editor/src/components/inserter/menu.js index a6b23c124e58..fc3905f59d03 100644 --- a/packages/block-editor/src/components/inserter/menu.js +++ b/packages/block-editor/src/components/inserter/menu.js @@ -34,6 +34,7 @@ import { createBlock, isUnmodifiedDefaultBlock, getBlockType, + getBlockFromExample, } from '@wordpress/blocks'; import { withDispatch, withSelect } from '@wordpress/data'; import { withInstanceId, compose, withSafeTimeout } from '@wordpress/compose'; @@ -391,11 +392,11 @@ export class InserterMenu extends Component {
diff --git a/packages/block-library/src/button/index.js b/packages/block-library/src/button/index.js index 80f10dd9672b..83a01deff055 100644 --- a/packages/block-library/src/button/index.js +++ b/packages/block-library/src/button/index.js @@ -21,6 +21,13 @@ export const settings = { description: __( 'Prompt visitors to take action with a button-style link.' ), icon, keywords: [ __( 'link' ) ], + example: { + attributes: { + className: 'is-style-fill', + backgroundColor: 'vivid-green-cyan', + text: __( 'Call to Action' ), + }, + }, supports: { align: true, alignWide: false, diff --git a/packages/block-library/src/calendar/index.js b/packages/block-library/src/calendar/index.js index f43f5c288f44..b63eb51188af 100644 --- a/packages/block-library/src/calendar/index.js +++ b/packages/block-library/src/calendar/index.js @@ -20,5 +20,6 @@ export const settings = { supports: { align: true, }, + example: {}, edit, }; diff --git a/packages/block-library/src/code/index.js b/packages/block-library/src/code/index.js index 1430dc7f27ad..e23a740b9d5e 100644 --- a/packages/block-library/src/code/index.js +++ b/packages/block-library/src/code/index.js @@ -20,6 +20,15 @@ export const settings = { title: __( 'Code' ), description: __( 'Display code snippets that respect your spacing and tabs.' ), icon, + example: { + attributes: { + content: __( '// A "block" is the abstract term used' ) + '\n' + + __( '// to describe units of markup that,' ) + '\n' + + __( '// when composed together, form the' ) + '\n' + + __( '// content or layout of a page.' ) + '\n' + + __( 'registerBlockType( name, settings );' ), + }, + }, supports: { html: false, }, diff --git a/packages/block-library/src/columns/index.js b/packages/block-library/src/columns/index.js index e4a0d7b4b08e..71f9ff081ec1 100644 --- a/packages/block-library/src/columns/index.js +++ b/packages/block-library/src/columns/index.js @@ -24,8 +24,51 @@ export const settings = { align: [ 'wide', 'full' ], html: false, }, + example: { + innerBlocks: [ + { + name: 'core/column', + innerBlocks: [ + { + name: 'core/paragraph', + attributes: { + content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent et eros eu felis pellentesque efficitur. Nam dapibus felis malesuada tincidunt rhoncus. Integer non malesuada tortor.', + }, + }, + { + name: 'core/image', + attributes: { + url: 'https://upload.wikimedia.org/wikipedia/commons/9/95/Windbuchencom.jpg', + }, + }, + { + name: 'core/paragraph', + attributes: { + content: 'Suspendisse commodo neque lacus, a dictum orci interdum et. Ut vel mi ut leo fringilla rutrum.', + }, + }, + ], + }, + { + name: 'core/column', + innerBlocks: [ + { + name: 'core/paragraph', + attributes: { + content: __( 'Etiam et egestas lorem. Vivamus sagittis sit amet dolor quis lobortis. Integer sed fermentum arcu, id vulputate lacus. Etiam fermentum sem eu quam hendrerit, eget faucibus urna pulvinar.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + content: __( 'Nam risus massa, ullamcorper consectetur eros fermentum, porta aliquet ligula. Sed vel mauris nec enim ultricies commodo.' ), + }, + }, + ], + }, + ], + }, deprecated, edit, save, }; - diff --git a/packages/block-library/src/cover/index.js b/packages/block-library/src/cover/index.js index 2a0727283dce..57e568ded8e6 100644 --- a/packages/block-library/src/cover/index.js +++ b/packages/block-library/src/cover/index.js @@ -24,6 +24,23 @@ export const settings = { supports: { align: true, }, + example: { + attributes: { + customOverlayColor: '#065174', + dimRatio: 40, + url: 'https://upload.wikimedia.org/wikipedia/commons/9/95/Windbuchencom.jpg', + }, + innerBlocks: [ + { + name: 'core/paragraph', + attributes: { + customFontSize: 48, + content: __( 'Snow Patrol' ), + align: 'center', + }, + }, + ], + }, transforms, save, edit, diff --git a/packages/block-library/src/gallery/index.js b/packages/block-library/src/gallery/index.js index 7c2d29c0c413..0cc414f81100 100644 --- a/packages/block-library/src/gallery/index.js +++ b/packages/block-library/src/gallery/index.js @@ -22,6 +22,15 @@ export const settings = { description: __( 'Display multiple images in a rich gallery.' ), icon, keywords: [ __( 'images' ), __( 'photos' ) ], + example: { + attributes: { + columns: 2, + images: [ + { url: 'https://upload.wikimedia.org/wikipedia/commons/c/c3/Glacial_lakes%2C_Bhutan.jpg' }, + { url: 'https://upload.wikimedia.org/wikipedia/commons/0/01/Sediment_off_the_Yucatan_Peninsula.jpg' }, + ], + }, + }, supports: { align: true, }, diff --git a/packages/block-library/src/group/index.js b/packages/block-library/src/group/index.js index 530dc210865b..d3bcfb86dca1 100644 --- a/packages/block-library/src/group/index.js +++ b/packages/block-library/src/group/index.js @@ -22,12 +22,66 @@ export const settings = { icon, description: __( 'A block that groups other blocks.' ), keywords: [ __( 'container' ), __( 'wrapper' ), __( 'row' ), __( 'section' ) ], + example: { + attributes: { + customBackgroundColor: '#ffffff', + }, + innerBlocks: [ + { + name: 'core/paragraph', + attributes: { + customTextColor: '#cf2e2e', + fontSize: 'large', + content: __( 'One.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + customTextColor: '#ff6900', + fontSize: 'large', + content: __( 'Two.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + customTextColor: '#fcb900', + fontSize: 'large', + content: __( 'Three.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + customTextColor: '#00d084', + fontSize: 'large', + content: __( 'Four.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + customTextColor: '#0693e3', + fontSize: 'large', + content: __( 'Five.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + customTextColor: '#9b51e0', + fontSize: 'large', + content: __( 'Six.' ), + }, + }, + ], + }, supports: { align: [ 'wide', 'full' ], anchor: true, html: false, }, - transforms: { from: [ { diff --git a/packages/block-library/src/heading/index.js b/packages/block-library/src/heading/index.js index 1dc024193e4a..ce2c1f29c528 100644 --- a/packages/block-library/src/heading/index.js +++ b/packages/block-library/src/heading/index.js @@ -25,6 +25,12 @@ export const settings = { className: false, anchor: true, }, + example: { + attributes: { + content: __( 'Code is Poetry' ), + level: 2, + }, + }, transforms, deprecated, merge( attributes, attributesToMerge ) { diff --git a/packages/block-library/src/html/index.js b/packages/block-library/src/html/index.js index bcfec8fb79f8..5d1ea9e0860f 100644 --- a/packages/block-library/src/html/index.js +++ b/packages/block-library/src/html/index.js @@ -21,6 +21,11 @@ export const settings = { description: __( 'Add custom HTML code and preview it as you edit.' ), icon, keywords: [ __( 'embed' ) ], + example: { + attributes: { + content: '' + __( 'Welcome to the wonderful world of blocks…' ) + '', + }, + }, supports: { customClassName: false, className: false, diff --git a/packages/block-library/src/image/index.js b/packages/block-library/src/image/index.js index 210450c67b6d..2cd1ddaaa3b4 100644 --- a/packages/block-library/src/image/index.js +++ b/packages/block-library/src/image/index.js @@ -25,6 +25,13 @@ export const settings = { 'img', // "img" is not translated as it is intended to reflect the HTML tag. __( 'photo' ), ], + example: { + attributes: { + sizeSlug: 'large', + url: 'https://upload.wikimedia.org/wikipedia/commons/1/15/MtBlanc1.JPG', + caption: __( 'Mont Blanc appears—still, snowy, and serene.' ), + }, + }, styles: [ { name: 'default', label: _x( 'Default', 'block style' ), isDefault: true }, { name: 'circle-mask', label: _x( 'Circle Mask', 'block style' ) }, diff --git a/packages/block-library/src/list/index.js b/packages/block-library/src/list/index.js index d7d857502b1a..f2423db6f322 100644 --- a/packages/block-library/src/list/index.js +++ b/packages/block-library/src/list/index.js @@ -24,6 +24,11 @@ export const settings = { supports: { className: false, }, + example: { + attributes: { + values: '
  • Alice.
  • The White Rabbit.
  • The Cheshire Cat.
  • The Mad Hatter.
  • The Queen of Hearts.
    • ', + }, + }, transforms, merge( attributes, attributesToMerge ) { const { values } = attributesToMerge; diff --git a/packages/block-library/src/media-text/index.js b/packages/block-library/src/media-text/index.js index b20dc9693baf..242bcddf2fbc 100644 --- a/packages/block-library/src/media-text/index.js +++ b/packages/block-library/src/media-text/index.js @@ -26,6 +26,26 @@ export const settings = { align: [ 'wide', 'full' ], html: false, }, + example: { + attributes: { + mediaType: 'image', + mediaUrl: 'https://upload.wikimedia.org/wikipedia/commons/d/d4/Biologia_Centrali-Americana_-_Cantorchilus_semibadius_1902.jpg', + }, + innerBlocks: [ + { + name: 'core/paragraph', + attributes: { + content: __( 'The wren
    Earns his living
    Noiselessly.' ), + }, + }, + { + name: 'core/paragraph', + attributes: { + content: __( '— Kobayashi Issa (一茶)' ), + }, + }, + ], + }, transforms, edit, save, diff --git a/packages/block-library/src/more/index.js b/packages/block-library/src/more/index.js index 9e73bdccb405..d61cb2001ff4 100644 --- a/packages/block-library/src/more/index.js +++ b/packages/block-library/src/more/index.js @@ -26,6 +26,7 @@ export const settings = { html: false, multiple: false, }, + example: {}, transforms, edit, save, diff --git a/packages/block-library/src/nextpage/index.js b/packages/block-library/src/nextpage/index.js index 99524951cecd..9f39f881d83d 100644 --- a/packages/block-library/src/nextpage/index.js +++ b/packages/block-library/src/nextpage/index.js @@ -26,6 +26,7 @@ export const settings = { className: false, html: false, }, + example: {}, transforms, edit, save, diff --git a/packages/block-library/src/paragraph/index.js b/packages/block-library/src/paragraph/index.js index 4221e72c85c1..63ff90b908fa 100644 --- a/packages/block-library/src/paragraph/index.js +++ b/packages/block-library/src/paragraph/index.js @@ -24,7 +24,9 @@ export const settings = { keywords: [ __( 'text' ) ], example: { attributes: { - content: __( 'Start writing, no matter what. The water does not flow until the faucet is turned on.' ), + content: __( 'In a village of La Mancha, the name of which I have no desire to call to mind, there lived not long since one of those gentlemen that keep a lance in the lance-rack, an old buckler, a lean hack, and a greyhound for coursing.' ), + customFontSize: 28, + dropCap: true, }, }, supports: { diff --git a/packages/block-library/src/preformatted/index.js b/packages/block-library/src/preformatted/index.js index eee13ab37f6f..8a0bed677273 100644 --- a/packages/block-library/src/preformatted/index.js +++ b/packages/block-library/src/preformatted/index.js @@ -20,6 +20,13 @@ export const settings = { title: __( 'Preformatted' ), description: __( 'Add text that respects your spacing and tabs, and also allows styling.' ), icon, + example: { + attributes: { + content: __( 'EXT. XANADU - FAINT DAWN - 1940 (MINIATURE)' ) + '\n' + + __( 'Window, very small in the distance, illuminated.' ) + '\n' + + __( 'All around this is an almost totally black screen. Now, as the camera moves slowly towards the window which is almost a postage stamp in the frame, other forms appear;' ), + }, + }, transforms, edit, save, diff --git a/packages/block-library/src/pullquote/index.js b/packages/block-library/src/pullquote/index.js index 944f7562385b..c3dfcdeed9b9 100644 --- a/packages/block-library/src/pullquote/index.js +++ b/packages/block-library/src/pullquote/index.js @@ -21,6 +21,12 @@ export const settings = { title: __( 'Pullquote' ), description: __( 'Give special visual emphasis to a quote from your text.' ), icon, + example: { + attributes: { + value: '

    ' + __( 'One of the hardest things to do in technology is disrupt yourself.' ) + '

    ', + citation: 'Matt Mullenweg', + }, + }, styles: [ { name: 'default', label: _x( 'Default', 'block style' ), isDefault: true }, { name: SOLID_COLOR_STYLE_NAME, label: __( 'Solid Color' ) }, diff --git a/packages/block-library/src/quote/index.js b/packages/block-library/src/quote/index.js index 8eb2a88be939..e7d733d41e3d 100644 --- a/packages/block-library/src/quote/index.js +++ b/packages/block-library/src/quote/index.js @@ -21,7 +21,14 @@ export const settings = { title: __( 'Quote' ), description: __( 'Give quoted text visual emphasis. "In quoting others, we cite ourselves." — Julio Cortázar' ), icon, - keywords: [ __( 'blockquote' ) ], + keywords: [ __( 'blockquote' ), __( 'cite' ) ], + example: { + attributes: { + value: '

    ' + __( 'In quoting others, we cite ourselves.' ) + '

    ', + citation: 'Julio Cortázar', + className: 'is-style-large', + }, + }, styles: [ { name: 'default', label: _x( 'Default', 'block style' ), isDefault: true }, { name: 'large', label: _x( 'Large', 'block style' ) }, diff --git a/packages/block-library/src/rss/index.js b/packages/block-library/src/rss/index.js index 46260d7751d0..3ae196e75aea 100644 --- a/packages/block-library/src/rss/index.js +++ b/packages/block-library/src/rss/index.js @@ -20,5 +20,10 @@ export const settings = { align: true, html: false, }, + example: { + attributes: { + feedURL: 'https://wordpress.org', + }, + }, edit, }; diff --git a/packages/block-library/src/search/index.js b/packages/block-library/src/search/index.js index 9023ccde6979..eb9ab982e831 100644 --- a/packages/block-library/src/search/index.js +++ b/packages/block-library/src/search/index.js @@ -19,5 +19,6 @@ export const settings = { supports: { align: true, }, + example: {}, edit, }; diff --git a/packages/block-library/src/separator/index.js b/packages/block-library/src/separator/index.js index a1d7eb8bd08e..37948d1d727a 100644 --- a/packages/block-library/src/separator/index.js +++ b/packages/block-library/src/separator/index.js @@ -21,6 +21,13 @@ export const settings = { description: __( 'Create a break between ideas or sections with a horizontal separator.' ), icon, keywords: [ __( 'horizontal-line' ), 'hr', __( 'divider' ) ], + example: { + attributes: { + customColor: '#065174', + className: 'is-style-wide', + + }, + }, styles: [ { name: 'default', label: __( 'Default' ), isDefault: true }, { name: 'wide', label: __( 'Wide Line' ) }, diff --git a/packages/block-library/src/social-links/index.js b/packages/block-library/src/social-links/index.js index 1e9df3194865..651ef3ca9f1e 100644 --- a/packages/block-library/src/social-links/index.js +++ b/packages/block-library/src/social-links/index.js @@ -20,6 +20,13 @@ export const settings = { supports: { align: [ 'left', 'center', 'right' ], }, + example: { + innerBlocks: [ + { name: 'core/social-link-wordpress', attributes: { url: 'https://wordpress.org' } }, + { name: 'core/social-link-facebook', attributes: { url: 'https://www.facebook.com/WordPress/' } }, + { name: 'core/social-link-twitter', attributes: { url: 'https://twitter.com/WordPress' } }, + ], + }, styles: [ { name: 'default', label: __( 'Default' ), isDefault: true }, { name: 'logos-only', label: __( 'Logos Only' ) }, diff --git a/packages/block-library/src/table/index.js b/packages/block-library/src/table/index.js index b8bd0893e87e..cb4e69f1988f 100644 --- a/packages/block-library/src/table/index.js +++ b/packages/block-library/src/table/index.js @@ -21,6 +21,76 @@ export const settings = { title: __( 'Table' ), description: __( 'Insert a table — perfect for sharing charts and data.' ), icon, + example: { + attributes: { + head: [ { + cells: [ + { + content: __( 'Version' ), + tag: 'th', + }, + { + content: __( 'Jazz Musician' ), + tag: 'th', + }, + { + content: __( 'Release Date' ), + tag: 'th', + }, + ], + } ], + body: [ + { + cells: [ + { + content: '5.2', + tag: 'td', + }, + { + content: 'Jaco Pastorius', + tag: 'td', + }, + { + content: __( 'May 7, 2019' ), + tag: 'td', + }, + ], + }, + { + cells: [ + { + content: '5.1', + tag: 'td', + }, + { + content: 'Betty Carter', + tag: 'td', + }, + { + content: __( 'February 21, 2019' ), + tag: 'td', + }, + ], + }, + { + cells: [ + { + content: '5.0', + tag: 'td', + }, + { + content: 'Bebo Valdés', + tag: 'td', + }, + { + content: __( 'December 6, 2018' ), + tag: 'td', + }, + ], + }, + ], + }, + }, styles: [ { name: 'regular', label: _x( 'Default', 'block style' ), isDefault: true }, { name: 'stripes', label: __( 'Stripes' ) }, diff --git a/packages/block-library/src/verse/index.js b/packages/block-library/src/verse/index.js index ffabff1dba48..4bf42fea4b94 100644 --- a/packages/block-library/src/verse/index.js +++ b/packages/block-library/src/verse/index.js @@ -21,6 +21,16 @@ export const settings = { title: __( 'Verse' ), description: __( 'Insert poetry. Use special spacing formats. Or quote song lyrics.' ), icon, + example: { + attributes: { + content: __( 'WHAT was he doing, the great god Pan,' ) + '
    ' + + __( ' Down in the reeds by the river?' ) + '
    ' + + __( 'Spreading ruin and scattering ban,' ) + '
    ' + + __( 'Splashing and paddling with hoofs of a goat,' ) + '
    ' + + __( 'And breaking the golden lilies afloat' ) + '
    ' + + __( ' With the dragon-fly on the river.' ), + }, + }, keywords: [ __( 'poetry' ) ], transforms, deprecated, diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 26e4ad5624ed..1af3f49adef8 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -273,6 +273,19 @@ _Returns_ - `string`: The block's default class. +# **getBlockFromExample** + +Create a block object from the example API. + +_Parameters_ + +- _name_ `string`: +- _example_ `Object`: + +_Returns_ + +- `Object`: block. + # **getBlockMenuDefaultClassName** Returns the block's default menu item classname from its name. diff --git a/packages/blocks/src/api/factory.js b/packages/blocks/src/api/factory.js index 8d659b1c8788..fae2e0e4da9c 100644 --- a/packages/blocks/src/api/factory.js +++ b/packages/blocks/src/api/factory.js @@ -15,6 +15,7 @@ import { uniq, isFunction, isEmpty, + map, } from 'lodash'; /** @@ -461,3 +462,17 @@ export function switchToBlockType( blocks, name ) { return applyFilters( 'blocks.switchToBlockType.transformedBlock', transformedBlock, blocks ); } ); } + +/** + * Create a block object from the example API. + * + * @param {string} name + * @param {Object} example + * + * @return {Object} block. + */ +export const getBlockFromExample = ( name, example ) => { + return createBlock( name, example.attributes, map( + example.innerBlocks, ( innerBlock ) => getBlockFromExample( innerBlock.name, innerBlock ) + ) ); +}; diff --git a/packages/blocks/src/api/index.js b/packages/blocks/src/api/index.js index 68e60ed43952..62074213559e 100644 --- a/packages/blocks/src/api/index.js +++ b/packages/blocks/src/api/index.js @@ -5,6 +5,7 @@ export { switchToBlockType, getBlockTransforms, findTransform, + getBlockFromExample, } from './factory'; export { default as parse,