diff --git a/blocks/README.md b/blocks/README.md index f858a184fc3a46..81eab6dd91d7d3 100644 --- a/blocks/README.md +++ b/blocks/README.md @@ -117,7 +117,7 @@ add_action( 'enqueue_block_editor_assets', 'random_image_enqueue_block_editor_as // block.js ( function( blocks, element ) { var el = element.createElement, - query = blocks.query; + source = blocks.source; function RandomImage( props ) { var src = 'http://lorempixel.com/400/200/' + props.category; @@ -138,7 +138,7 @@ add_action( 'enqueue_block_editor_assets', 'random_image_enqueue_block_editor_as attributes: { category: { type: 'string', - source: query.attr( 'img', 'alt' ) + source: source.attr( 'img', 'alt' ) } }, @@ -207,7 +207,7 @@ encoding the values into the published post's markup, and then retrieving them the next time the post is edited. This is the motivation for the block's `attributes` property. The shape of this object matches that of the attributes object we'd like to receive, where each value is a -[__matcher__](http://github.com/aduth/hpq) +[__source__](http://github.com/aduth/hpq) which tries to find the desired value from the markup of the block. In the random image block above, we've given the `alt` attribute of the image a @@ -237,7 +237,7 @@ editor interface where blocks are implemented. - `attributes: Object | Function` - An object of attribute schemas, where the keys of the object define the shape of attributes, and each value an object schema describing the `type`, `default` (optional), and - [`source`](http://gutenberg-devdoc.surge.sh/reference/attribute-matchers/) + [`source`](http://gutenberg-devdoc.surge.sh/reference/attribute-sources/) (optional) of the attribute. If `source` is omitted, the attribute is serialized into the block's comment delimiters. Alternatively, define `attributes` as a function which returns the attributes object. diff --git a/blocks/api/index.js b/blocks/api/index.js index 438807240636df..b25e28735a5c84 100644 --- a/blocks/api/index.js +++ b/blocks/api/index.js @@ -1,9 +1,9 @@ /** * External dependencies */ -import * as query from './query'; +import * as source from './source'; -export { query }; +export { source }; export { createBlock, switchToBlockType } from './factory'; export { default as parse } from './parser'; export { default as pasteHandler } from './paste'; diff --git a/blocks/api/parser.js b/blocks/api/parser.js index 65b5cc5dedde8c..a211e89f86ad76 100644 --- a/blocks/api/parser.js +++ b/blocks/api/parser.js @@ -31,7 +31,7 @@ import { isValidBlock } from './validation'; * @return {Boolean} Whether function is an attribute source */ export function isValidSource( source ) { - return !! source && '_wpBlocksKnownMatcher' in source; + return !! source && '_wpBlocksKnownSource' in source; } /** diff --git a/blocks/api/paste.js b/blocks/api/paste.js index f1ea90c21879b5..8428572867dc5c 100644 --- a/blocks/api/paste.js +++ b/blocks/api/paste.js @@ -90,7 +90,7 @@ export default function( nodes ) { const transformsFrom = get( blockType, 'transforms.from', [] ); const transform = find( transformsFrom, ( { type } ) => type === 'raw' ); - if ( ! transform || ! transform.matcher( node ) ) { + if ( ! transform || ! transform.source( node ) ) { return acc; } diff --git a/blocks/api/query.js b/blocks/api/query.js deleted file mode 100644 index 72a7ed4db08f9c..00000000000000 --- a/blocks/api/query.js +++ /dev/null @@ -1,63 +0,0 @@ -/** - * WordPress dependencies - */ -import { createElement } from '@wordpress/element'; - -/** - * External dependencies - */ -import { nodeListToReact, nodeToReact } from 'dom-react'; -import { flow } from 'lodash'; -import { - attr as originalAttr, - prop as originalProp, - html as originalHtml, - text as originalText, - query as originalQuery, -} from 'hpq'; - -/** - * Given a matcher function creator, returns a new function which applies an - * internal flag to the created matcher. - * - * @param {Function} fn Original matcher function creator - * @return {Function} Modified matcher function creator - */ -function withKnownMatcherFlag( fn ) { - return flow( fn, ( matcher ) => { - matcher._wpBlocksKnownMatcher = true; - return matcher; - } ); -} - -export const attr = withKnownMatcherFlag( originalAttr ); -export const prop = withKnownMatcherFlag( originalProp ); -export const html = withKnownMatcherFlag( originalHtml ); -export const text = withKnownMatcherFlag( originalText ); -export const query = withKnownMatcherFlag( originalQuery ); -export const children = withKnownMatcherFlag( ( selector ) => { - return ( domNode ) => { - let match = domNode; - - if ( selector ) { - match = domNode.querySelector( selector ); - } - - if ( match ) { - return nodeListToReact( match.childNodes || [], createElement ); - } - - return []; - }; -} ); -export const node = withKnownMatcherFlag( ( selector ) => { - return ( domNode ) => { - let match = domNode; - - if ( selector ) { - match = domNode.querySelector( selector ); - } - - return nodeToReact( match, createElement ); - }; -} ); diff --git a/blocks/api/source.js b/blocks/api/source.js new file mode 100644 index 00000000000000..eee04d56e604fa --- /dev/null +++ b/blocks/api/source.js @@ -0,0 +1,63 @@ +/** + * WordPress dependencies + */ +import { createElement } from '@wordpress/element'; + +/** + * External dependencies + */ +import { nodeListToReact, nodeToReact } from 'dom-react'; +import { flow } from 'lodash'; +import { + attr as originalAttr, + prop as originalProp, + html as originalHtml, + text as originalText, + query as originalQuery, +} from 'hpq'; + +/** + * Given a source function creator, returns a new function which applies an + * internal flag to the created source. + * + * @param {Function} fn Original source function creator + * @return {Function} Modified source function creator + */ +function withKnownSourceFlag( fn ) { + return flow( fn, ( source ) => { + source._wpBlocksKnownSource = true; + return source; + } ); +} + +export const attr = withKnownSourceFlag( originalAttr ); +export const prop = withKnownSourceFlag( originalProp ); +export const html = withKnownSourceFlag( originalHtml ); +export const text = withKnownSourceFlag( originalText ); +export const query = withKnownSourceFlag( originalQuery ); +export const children = withKnownSourceFlag( ( selector ) => { + return ( domNode ) => { + let match = domNode; + + if ( selector ) { + match = domNode.querySelector( selector ); + } + + if ( match ) { + return nodeListToReact( match.childNodes || [], createElement ); + } + + return []; + }; +} ); +export const node = withKnownSourceFlag( ( selector ) => { + return ( domNode ) => { + let match = domNode; + + if ( selector ) { + match = domNode.querySelector( selector ); + } + + return nodeToReact( match, createElement ); + }; +} ); diff --git a/blocks/api/test/parser.js b/blocks/api/test/parser.js index 9c513e87ac4b91..3bf03f236b006a 100644 --- a/blocks/api/test/parser.js +++ b/blocks/api/test/parser.js @@ -6,7 +6,7 @@ import { noop } from 'lodash'; /** * Internal dependencies */ -import { text, attr, html } from '../query'; +import { text, attr, html } from '../source'; import { isValidSource, getBlockAttributes, diff --git a/blocks/api/test/serializer.js b/blocks/api/test/serializer.js index 8498e9d5cdda28..5cfe233e705aa5 100644 --- a/blocks/api/test/serializer.js +++ b/blocks/api/test/serializer.js @@ -6,7 +6,7 @@ import { createElement, Component } from '@wordpress/element'; /** * Internal dependencies */ -import { text } from '../query'; +import { text } from '../source'; import serialize, { getCommentAttributes, getBeautifulContent, diff --git a/blocks/api/test/query.js b/blocks/api/test/source.js similarity index 62% rename from blocks/api/test/query.js rename to blocks/api/test/source.js index c4cae0db0753aa..957c60df466879 100644 --- a/blocks/api/test/query.js +++ b/blocks/api/test/source.js @@ -11,44 +11,44 @@ import { renderToString } from '@wordpress/element'; /** * Internal dependencies */ -import * as query from '../query'; +import * as sources from '../source'; -describe( 'query', () => { - it( 'should generate matchers which apply internal flag', () => { - for ( const matcherFn in query ) { - expect( query[ matcherFn ]()._wpBlocksKnownMatcher ).toBe( true ); +describe( 'sources', () => { + it( 'should generate sources which apply internal flag', () => { + for ( const sourceFn in sources ) { + expect( sources[ sourceFn ]()._wpBlocksKnownSource ).toBe( true ); } } ); describe( 'children()', () => { - it( 'should return a matcher function', () => { - const matcher = query.children(); + it( 'should return a source function', () => { + const source = sources.children(); - expect( typeof matcher ).toBe( 'function' ); + expect( typeof source ).toBe( 'function' ); } ); it( 'should return HTML equivalent WPElement of matched element', () => { // Assumption here is that we can cleanly convert back and forth // between a string and WPElement representation const html = '

A delicious sundae dessert

'; - const match = parse( html, query.children() ); + const match = parse( html, sources.children() ); expect( renderToString( match ) ).toBe( html ); } ); } ); describe( 'node()', () => { - it( 'should return a matcher function', () => { - const matcher = query.node(); + it( 'should return a source function', () => { + const source = sources.node(); - expect( typeof matcher ).toBe( 'function' ); + expect( typeof source ).toBe( 'function' ); } ); it( 'should return HTML equivalent WPElement of matched element', () => { // Assumption here is that we can cleanly convert back and forth // between a string and WPElement representation const html = '

A delicious sundae dessert

'; - const match = parse( html, query.node() ); + const match = parse( html, sources.node() ); expect( renderToString( match ) ).toBe( `${ html }` ); } ); diff --git a/blocks/library/button/index.js b/blocks/library/button/index.js index 885051f661ce26..29d7567b996e46 100644 --- a/blocks/library/button/index.js +++ b/blocks/library/button/index.js @@ -9,7 +9,7 @@ import { IconButton } from '@wordpress/components'; */ import './style.scss'; import './block.scss'; -import { registerBlockType, query } from '../../api'; +import { registerBlockType, source } from '../../api'; import Editable from '../../editable'; import UrlInput from '../../url-input'; import BlockControls from '../../block-controls'; @@ -17,7 +17,7 @@ import BlockAlignmentToolbar from '../../block-alignment-toolbar'; import ColorPalette from '../../color-palette'; import InspectorControls from '../../inspector-controls'; -const { attr, children } = query; +const { attr, children } = source; registerBlockType( 'core/button', { title: __( 'Button' ), diff --git a/blocks/library/code/index.js b/blocks/library/code/index.js index d6ba0c818b6c46..65d610b9e69adc 100644 --- a/blocks/library/code/index.js +++ b/blocks/library/code/index.js @@ -12,9 +12,9 @@ import { __ } from '@wordpress/i18n'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, query, createBlock } from '../../api'; +import { registerBlockType, source, createBlock } from '../../api'; -const { prop } = query; +const { prop } = source; registerBlockType( 'core/code', { title: __( 'Code' ), diff --git a/blocks/library/cover-image/index.js b/blocks/library/cover-image/index.js index ba8294583b3c00..1f012a7943b98d 100644 --- a/blocks/library/cover-image/index.js +++ b/blocks/library/cover-image/index.js @@ -10,7 +10,7 @@ import classnames from 'classnames'; */ import './style.scss'; import './block.scss'; -import { registerBlockType, query } from '../../api'; +import { registerBlockType, source } from '../../api'; import Editable from '../../editable'; import MediaUploadButton from '../../media-upload-button'; import BlockControls from '../../block-controls'; @@ -19,7 +19,7 @@ import InspectorControls from '../../inspector-controls'; import ToggleControl from '../../inspector-controls/toggle-control'; import BlockDescription from '../../block-description'; -const { text } = query; +const { text } = source; const validAlignments = [ 'left', 'center', 'right', 'wide', 'full' ]; diff --git a/blocks/library/cover-text/index.js b/blocks/library/cover-text/index.js index c67c3698d81335..6c3148e26e79e0 100644 --- a/blocks/library/cover-text/index.js +++ b/blocks/library/cover-text/index.js @@ -8,7 +8,7 @@ import { concatChildren } from '@wordpress/element'; * Internal dependencies */ import './block.scss'; -import { registerBlockType, query as hpq } from '../../api'; +import { registerBlockType, source } from '../../api'; import AlignmentToolbar from '../../alignment-toolbar'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; @@ -18,7 +18,7 @@ import InspectorControls from '../../inspector-controls'; import ToggleControl from '../../inspector-controls/toggle-control'; import BlockDescription from '../../block-description'; -const { children, query } = hpq; +const { children, query } = source; registerBlockType( 'core/cover-text', { title: __( 'Cover Text' ), diff --git a/blocks/library/embed/index.js b/blocks/library/embed/index.js index c1bbdfae20254b..fc6c17353929a7 100644 --- a/blocks/library/embed/index.js +++ b/blocks/library/embed/index.js @@ -16,12 +16,12 @@ import { addQueryArgs } from '@wordpress/url'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, query, createBlock } from '../../api'; +import { registerBlockType, source, createBlock } from '../../api'; import Editable from '../../editable'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; -const { children } = query; +const { children } = source; // These embeds do not work in sandboxes const HOSTS_NO_PREVIEWS = [ 'facebook.com' ]; diff --git a/blocks/library/freeform/index.js b/blocks/library/freeform/index.js index 0e8d2a3272afd3..496549cba220e9 100644 --- a/blocks/library/freeform/index.js +++ b/blocks/library/freeform/index.js @@ -7,10 +7,10 @@ import { __ } from '@wordpress/i18n'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, query, setUnknownTypeHandlerName } from '../../api'; +import { registerBlockType, source, setUnknownTypeHandlerName } from '../../api'; import OldEditor from './old-editor'; -const { prop } = query; +const { prop } = source; registerBlockType( 'core/freeform', { title: __( 'Classic Text' ), diff --git a/blocks/library/heading/index.js b/blocks/library/heading/index.js index c7936f82253316..d056db825f7a9c 100644 --- a/blocks/library/heading/index.js +++ b/blocks/library/heading/index.js @@ -9,14 +9,14 @@ import { Toolbar } from '@wordpress/components'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, createBlock, query } from '../../api'; +import { registerBlockType, createBlock, source } from '../../api'; import Editable from '../../editable'; import BlockControls from '../../block-controls'; import InspectorControls from '../../inspector-controls'; import AlignmentToolbar from '../../alignment-toolbar'; import BlockDescription from '../../block-description'; -const { children, prop } = query; +const { children, prop } = source; registerBlockType( 'core/heading', { title: __( 'Heading' ), @@ -58,7 +58,7 @@ registerBlockType( 'core/heading', { }, { type: 'raw', - matcher: ( node ) => /H\d/.test( node.nodeName ), + source: ( node ) => /H\d/.test( node.nodeName ), attributes: { content: children( 'h1,h2,h3,h4,h5,h6' ), nodeName: prop( 'h1,h2,h3,h4,h5,h6', 'nodeName' ), diff --git a/blocks/library/html/index.js b/blocks/library/html/index.js index 1bc908bd95d8dc..8fb70b5edcf178 100644 --- a/blocks/library/html/index.js +++ b/blocks/library/html/index.js @@ -13,10 +13,10 @@ import { Component } from '@wordpress/element'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, query } from '../../api'; +import { registerBlockType, source } from '../../api'; import BlockControls from '../../block-controls'; -const { html } = query; +const { html } = source; registerBlockType( 'core/html', { title: __( 'Custom HTML' ), diff --git a/blocks/library/image/index.js b/blocks/library/image/index.js index 7153ace8172595..8bfa867b1b7017 100644 --- a/blocks/library/image/index.js +++ b/blocks/library/image/index.js @@ -13,7 +13,7 @@ import { Placeholder, Dashicon, Toolbar, DropZone, FormFileUpload } from '@wordp * Internal dependencies */ import './style.scss'; -import { registerBlockType, query } from '../../api'; +import { registerBlockType, source } from '../../api'; import Editable from '../../editable'; import MediaUploadButton from '../../media-upload-button'; import InspectorControls from '../../inspector-controls'; @@ -23,7 +23,7 @@ import BlockAlignmentToolbar from '../../block-alignment-toolbar'; import BlockDescription from '../../block-description'; import UrlInputButton from '../../url-input/button'; -const { attr, children } = query; +const { attr, children } = source; registerBlockType( 'core/image', { title: __( 'Image' ), @@ -61,7 +61,7 @@ registerBlockType( 'core/image', { from: [ { type: 'raw', - matcher: ( node ) => ( + source: ( node ) => ( node.nodeName === 'IMG' || ( ! node.textContent && node.querySelector( 'img' ) ) ), diff --git a/blocks/library/list/index.js b/blocks/library/list/index.js index 46190f5d0392bb..fb6cab23c61c9f 100644 --- a/blocks/library/list/index.js +++ b/blocks/library/list/index.js @@ -13,11 +13,11 @@ import { __ } from '@wordpress/i18n'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, query as hpq, createBlock } from '../../api'; +import { registerBlockType, source, createBlock } from '../../api'; import Editable from '../../editable'; import BlockControls from '../../block-controls'; -const { children, prop } = hpq; +const { children, prop } = source; const fromBrDelimitedContent = ( content ) => { if ( undefined === content ) { @@ -116,7 +116,7 @@ registerBlockType( 'core/list', { }, { type: 'raw', - matcher: ( node ) => node.nodeName === 'OL' || node.nodeName === 'UL', + source: ( node ) => node.nodeName === 'OL' || node.nodeName === 'UL', attributes: { nodeName: prop( 'ol,ul', 'nodeName' ), values: children( 'ol,ul' ), diff --git a/blocks/library/paragraph/index.js b/blocks/library/paragraph/index.js index f79a1935100916..0818209d99eab6 100644 --- a/blocks/library/paragraph/index.js +++ b/blocks/library/paragraph/index.js @@ -8,7 +8,7 @@ import { concatChildren } from '@wordpress/element'; * Internal dependencies */ import './block.scss'; -import { registerBlockType, createBlock, query as hpq, setDefaultBlock } from '../../api'; +import { registerBlockType, createBlock, source, setDefaultBlock } from '../../api'; import AlignmentToolbar from '../../alignment-toolbar'; import BlockControls from '../../block-controls'; import Editable from '../../editable'; @@ -16,7 +16,7 @@ import InspectorControls from '../../inspector-controls'; import ToggleControl from '../../inspector-controls/toggle-control'; import BlockDescription from '../../block-description'; -const { children } = hpq; +const { children } = source; registerBlockType( 'core/paragraph', { title: __( 'Paragraph' ), @@ -50,7 +50,7 @@ registerBlockType( 'core/paragraph', { from: [ { type: 'raw', - matcher: ( node ) => ( + source: ( node ) => ( node.nodeName === 'P' && // Do not allow embedded content. ! node.querySelector( 'audio, canvas, embed, iframe, img, math, object, svg, video' ) diff --git a/blocks/library/preformatted/index.js b/blocks/library/preformatted/index.js index 4d796fe19fde8f..45379313e40e9d 100644 --- a/blocks/library/preformatted/index.js +++ b/blocks/library/preformatted/index.js @@ -7,10 +7,10 @@ import { __ } from '@wordpress/i18n'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, createBlock, query } from '../../api'; +import { registerBlockType, createBlock, source } from '../../api'; import Editable from '../../editable'; -const { children } = query; +const { children } = source; registerBlockType( 'core/preformatted', { title: __( 'Preformatted' ), diff --git a/blocks/library/pullquote/index.js b/blocks/library/pullquote/index.js index c255429b46f3e7..dfbedbc3734d25 100644 --- a/blocks/library/pullquote/index.js +++ b/blocks/library/pullquote/index.js @@ -8,12 +8,12 @@ import { __ } from '@wordpress/i18n'; */ import './style.scss'; import './block.scss'; -import { registerBlockType, query as hpq } from '../../api'; +import { registerBlockType, source } from '../../api'; import Editable from '../../editable'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; -const { children, query, node } = hpq; +const { children, query, node } = source; registerBlockType( 'core/pullquote', { diff --git a/blocks/library/quote/index.js b/blocks/library/quote/index.js index 4833643a0687e5..80af82a89f43a2 100644 --- a/blocks/library/quote/index.js +++ b/blocks/library/quote/index.js @@ -13,12 +13,12 @@ import { Toolbar } from '@wordpress/components'; * Internal dependencies */ import './block.scss'; -import { registerBlockType, createBlock, query as hpq } from '../../api'; +import { registerBlockType, createBlock, source } from '../../api'; import AlignmentToolbar from '../../alignment-toolbar'; import BlockControls from '../../block-controls'; import Editable from '../../editable'; -const { children, node, query } = hpq; +const { children, node, query } = source; registerBlockType( 'core/quote', { title: __( 'Quote' ), diff --git a/blocks/library/table/index.js b/blocks/library/table/index.js index 9fb4fb08334410..5b0812729c41c1 100644 --- a/blocks/library/table/index.js +++ b/blocks/library/table/index.js @@ -8,12 +8,12 @@ import { __ } from '@wordpress/i18n'; */ import './style.scss'; import './block.scss'; -import { registerBlockType, query as hpq } from '../../api'; +import { registerBlockType, source } from '../../api'; import TableBlock from './table-block'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; -const { children } = hpq; +const { children } = source; registerBlockType( 'core/table', { title: __( 'Table' ), diff --git a/blocks/library/text-columns/index.js b/blocks/library/text-columns/index.js index d5436735a8e4ca..c49240c91d032c 100644 --- a/blocks/library/text-columns/index.js +++ b/blocks/library/text-columns/index.js @@ -13,7 +13,7 @@ import { __ } from '@wordpress/i18n'; */ import './block.scss'; import './style.scss'; -import { registerBlockType, query as hpq } from '../../api'; +import { registerBlockType, source } from '../../api'; import BlockControls from '../../block-controls'; import BlockAlignmentToolbar from '../../block-alignment-toolbar'; import RangeControl from '../../inspector-controls/range-control'; @@ -21,7 +21,7 @@ import Editable from '../../editable'; import InspectorControls from '../../inspector-controls'; import BlockDescription from '../../block-description'; -const { children, query } = hpq; +const { children, query } = source; registerBlockType( 'core/text-columns', { title: __( 'Text Columns' ), diff --git a/blocks/library/verse/index.js b/blocks/library/verse/index.js index 6a2821f2ac0cbd..65aa3c2cd10a26 100644 --- a/blocks/library/verse/index.js +++ b/blocks/library/verse/index.js @@ -7,12 +7,12 @@ import { __ } from '@wordpress/i18n'; * Internal dependencies */ import './style.scss'; -import { registerBlockType, createBlock, query } from '../../api'; +import { registerBlockType, createBlock, source } from '../../api'; import Editable from '../../editable'; import InspectorControls from '../../inspector-controls'; import BlockDescription from '../../block-description'; -const { children } = query; +const { children } = source; registerBlockType( 'core/verse', { title: __( 'Verse' ), diff --git a/docs/attribute-matchers.md b/docs/attribute-matchers.md index ca79d2be3627e2..b11b453a320bd1 100644 --- a/docs/attribute-matchers.md +++ b/docs/attribute-matchers.md @@ -1,12 +1,12 @@ -# Attribute Matchers +# Attribute Sources -Attribute matchers are used to define the strategy by which block attribute values are extracted from saved post content. They provide a mechanism to map from the saved markup to a JavaScript representation of a block. +Attribute sources are used to define the strategy by which block attribute values are extracted from saved post content. They provide a mechanism to map from the saved markup to a JavaScript representation of a block. -Each matcher accepts an optional selector as the first argument. If a selector is specified, the matcher behavior will be run against the corresponding element(s) contained within the block. Otherwise it will be run against the block's root node. +Each source accepts an optional selector as the first argument. If a selector is specified, the source behavior will be run against the corresponding element(s) contained within the block. Otherwise it will be run against the block's root node. -Under the hood, attribute matchers are a superset of functionality provided by [hpq](https://github.com/aduth/hpq), a small library used to parse and query HTML markup into an object shape. In an object of attributes matchers, you can name the keys as you see fit. The resulting object will assign as a value to each key the result of its attribute matcher. +Under the hood, attribute sources are a superset of functionality provided by [hpq](https://github.com/aduth/hpq), a small library used to parse and query HTML markup into an object shape. In an object of attributes sources, you can name the keys as you see fit. The resulting object will assign as a value to each key the result of its attribute source. -## Common Matchers +## Common Sources ### `attr` @@ -46,7 +46,7 @@ _Example_: Extract child nodes from a paragraph of rich text. ### `query` -Use `query` to extract an array of values from markup. Entries of the array are determined by the selector argument, where each matched element within the block will have an entry structured corresponding to the second argument, an object of attribute matchers. +Use `query` to extract an array of values from markup. Entries of the array are determined by the selector argument, where each matched element within the block will have an entry structured corresponding to the second argument, an object of attribute sources. _Example_: Extract `src` and `alt` from each image element in the block's markup. diff --git a/docs/blocks-controls.md b/docs/blocks-controls.md index 0c5fda3082ed70..6bd6ba126ad69b 100644 --- a/docs/blocks-controls.md +++ b/docs/blocks-controls.md @@ -18,7 +18,7 @@ var el = wp.element.createElement, Editable = wp.blocks.Editable, BlockControls = wp.blocks.BlockControls, AlignmentToolbar = wp.blocks.AlignmentToolbar, - children = wp.blocks.query.children; + children = wp.blocks.source.children; registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-04', { title: 'Hello World (Step 4)', @@ -89,7 +89,7 @@ const { Editable, BlockControls, AlignmentToolbar, - query + source } = wp.blocks; const { children } = children; diff --git a/docs/blocks-editable.md b/docs/blocks-editable.md index c23ac980ba445f..a82d0c7c47e961 100644 --- a/docs/blocks-editable.md +++ b/docs/blocks-editable.md @@ -14,7 +14,7 @@ One challenge of maintaining the representation of a block as a JavaScript objec var el = wp.element.createElement, registerBlockType = wp.blocks.registerBlockType, Editable = wp.blocks.Editable, - children = wp.blocks.query.children; + children = wp.blocks.source.children; registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', { title: 'Hello World (Step 3)', @@ -60,8 +60,8 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', { ``` {% ESNext %} ```js -const { registerBlockType, Editable, query } = wp.blocks; -const { children } = query; +const { registerBlockType, Editable, source } = wp.blocks; +const { children } = source; registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', { title: 'Hello World (Step 3)', @@ -105,7 +105,7 @@ registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', { ``` {% end %} -When registering a new block type, the `attributes` property describes the shape of the attributes object you'd like to receive in the `edit` and `save` functions. Each value is a [matcher function](attribute-matchers.md) to find the desired value from the markup of the block. +When registering a new block type, the `attributes` property describes the shape of the attributes object you'd like to receive in the `edit` and `save` functions. Each value is a [source function](attribute-sources.md) to find the desired value from the markup of the block. In the code snippet above, when loading the editor, we will extract the `content` value as the children of the paragraph element in the saved post's markup. @@ -117,4 +117,4 @@ The `Editable` component can be considered as a super-powered `textarea` element Implementing this behavior as a component enables you as the block implementer to be much more granular about editable fields. Your block may not need `Editable` at all, or it may need many independent `Editable` elements, each operating on a subset of the overall block state. -Because `Editable` allows for nested nodes, you'll most often use it in conjunction with the `children` attribute matcher when extracting the value from saved content. +Because `Editable` allows for nested nodes, you'll most often use it in conjunction with the `children` attribute source when extracting the value from saved content. diff --git a/docs/glossary.md b/docs/glossary.md index 70a7fff8353ecb..0d1ffb72d54f63 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,7 +1,7 @@ # Glossary -- __Attribute matchers__: An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute matchers, where each value is the result of the attribute matcher function. -- __Attributes__: The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute matchers for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block. +- __Attribute sources__: An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function. +- __Attributes__: The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block. - __Block__: The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. - __Block name__: A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image` - __Block type__: In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition. diff --git a/docs/index.js b/docs/index.js index 50183ee4149898..5c7f4e37455b48 100644 --- a/docs/index.js +++ b/docs/index.js @@ -52,9 +52,9 @@ addStory( { addStory( { parents: [ 'reference' ], - name: 'attribute-matchers', - title: 'Attribute Matchers', - markdown: require( './attribute-matchers.md' ), + name: 'attribute-sources', + title: 'Attribute Sources', + markdown: require( './attribute-sources.md' ), } ); addStory( { diff --git a/docs/reference.md b/docs/reference.md index 3313c417fcd693..140fd4256676bd 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,6 +1,6 @@ # Reference -- [Attribute Matchers](./reference/attribute-matchers) +- [Attribute Sources](./reference/attribute-sources) - [Glossary](./reference/glossary) - [Design Principles](./reference/design-principles) - [Coding Guidelines](./reference/coding-guidelines)