diff --git a/blocks/README.md b/blocks/README.md index 01b88ba4e5c783..9768f57ba171d5 100644 --- a/blocks/README.md +++ b/blocks/README.md @@ -138,7 +138,9 @@ add_action( 'enqueue_block_editor_assets', 'random_image_enqueue_block_editor_as attributes: { category: { type: 'string', - source: source.attr( 'img', 'alt' ) + source: 'attribute', + attribute: 'alt', + selector: 'img', } }, @@ -238,8 +240,8 @@ editor interface where blocks are implemented. 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/attributes/) - (optional) of the attribute. If `source` is omitted, the attribute is - serialized into the block's comment delimiters. Alternatively, define + (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. - `category: string` - Slug of the block's category. The category is used to organize the blocks in the block inserter. diff --git a/docs/attributes.md b/docs/attributes.md index bffe0c1fd9210c..e742b16c77690c 100644 --- a/docs/attributes.md +++ b/docs/attributes.md @@ -8,21 +8,85 @@ Each source accepts an optional selector as the first argument. If a selector is 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. -### `attr` +### `attribute` -Use `attr` to extract the value of an attribute from markup. +Use `attribute` to extract the value of an attribute from markup. _Example_: Extract the `src` attribute from an image found in the block's markup. ```js { url: { - source: attr( 'img', 'src' ) + source: 'attribute', + selector: 'img', + attribute: 'src', } } // { "url": "https://lorempixel.com/1200/800/" } ``` +### `attribute` + +Use `attribute` to extract the value of an attribute from markup. + +_Example_: Extract the `src` attribute from an image found in the block's markup. + +```js +{ + url: { + source: 'attribute', + selector: 'img', + attribute: 'src', + } +} +// { "url": "https://lorempixel.com/1200/800/" } +``` + +### `property` + +Use `property` to extract the value of a property of a DOM Node from markup. + +_Example_: Extract the `nodeName` property from a heading's node. + +```js +{ + tagName: { + source: 'property', + selector: 'h1,h2,h3,h4,h5,h6', + property: 'nodeName', + } +} +// { "tagName": "h2" } +``` + +### `text` + +Use `text` to extract the inner text from markup. + +```js +{ + content: { + source: 'text', + selector: 'figcaption', + } +} +// { "content": "The inner text of the figcaption element" } +``` + +### `html` + +Use `html` to extract the inner HTML from markup. + +```js +{ + content: { + source: 'html', + selector: 'figcaption', + } +} +// { "content": "The inner text of the figcaption element" } +``` + ### `children` Use `children` to extract child nodes of the matched element, returned as an array of virtual elements. This is most commonly used in combination with the `Editable` component. @@ -32,13 +96,14 @@ _Example_: Extract child nodes from a paragraph of rich text. ```js { content: { - source: children( 'p' ) + source: 'children', + selector: 'p' } } // { // "content": [ // "Vestibulum eu ", -// { "type": "strong", "children": "tortor" }, +// { "type": "strong", "children": "tortor" }, // " vel urna." // ] // } @@ -53,14 +118,19 @@ _Example_: Extract `src` and `alt` from each image element in the block's markup ```js { images: { - source: query( 'img', { - url: attr( 'src' ) - alt: attr( 'alt' ) - } ) + source: 'query' + selector: 'img', + query: { + source: 'object', + object: { + url: { source: 'attribute', attribute: 'src' }, + alt: { source: 'attribute', attribute: 'alt' }, + }, + } } } // { -// "images": [ +// "images": [ // { "url": "https://lorempixel.com/1200/800/", "alt": "large image" }, // { "url": "https://lorempixel.com/50/50/", "alt": "small image" } // ] @@ -75,6 +145,7 @@ Attributes may be obtained from a post's meta rather than from the block's repre attributes: { author: { type: 'string', + source: 'meta', meta: 'author' }, }, diff --git a/docs/block-api.md b/docs/block-api.md index fcd1528866ed74..000a3f4094143b 100644 --- a/docs/block-api.md +++ b/docs/block-api.md @@ -76,11 +76,14 @@ Attributes provide the structured data needs of a block. They can exist in diffe attributes: { cover: { type: 'string', - source: attr( 'img', 'src' ), + source: 'attribute', + selector: 'img', + attribute: 'src', }, author: { type: 'string', - source: children( '.book-author' ), + source: 'children', + selector: '.book-author', }, pages: { type: 'number', diff --git a/docs/blocks-controls.md b/docs/blocks-controls.md index c68c6c0a9811a2..50d96ce1e3029b 100644 --- a/docs/blocks-controls.md +++ b/docs/blocks-controls.md @@ -17,8 +17,7 @@ var el = wp.element.createElement, registerBlockType = wp.blocks.registerBlockType, Editable = wp.blocks.Editable, BlockControls = wp.blocks.BlockControls, - AlignmentToolbar = wp.blocks.AlignmentToolbar, - children = wp.blocks.source.children; + AlignmentToolbar = wp.blocks.AlignmentToolbar; registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-04', { title: 'Hello World (Step 4)', @@ -30,7 +29,8 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-04', { attributes: { content: { type: 'array', - source: children( 'p' ) + source: 'children', + selector: 'p', } }, @@ -91,7 +91,6 @@ const { AlignmentToolbar, source } = wp.blocks; -const { children } = source; registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-04', { title: 'Hello World (Step 4)', @@ -103,7 +102,8 @@ registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-04', { attributes: { content: { type: 'array', - source: children( 'p' ), + source: 'children', + selector: 'p', }, }, diff --git a/docs/blocks-editable.md b/docs/blocks-editable.md index 484b8f99644480..7a5a9ce3fa77e4 100644 --- a/docs/blocks-editable.md +++ b/docs/blocks-editable.md @@ -13,8 +13,7 @@ One challenge of maintaining the representation of a block as a JavaScript objec ```js var el = wp.element.createElement, registerBlockType = wp.blocks.registerBlockType, - Editable = wp.blocks.Editable, - children = wp.blocks.source.children; + Editable = wp.blocks.Editable; registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', { title: 'Hello World (Step 3)', @@ -26,7 +25,8 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', { attributes: { content: { type: 'array', - source: children( 'p' ) + source: 'children', + selector: 'p', } }, @@ -61,7 +61,6 @@ registerBlockType( 'gutenberg-boilerplate-es5/hello-world-step-03', { {% ESNext %} ```js const { registerBlockType, Editable, source } = wp.blocks; -const { children } = source; registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', { title: 'Hello World (Step 3)', @@ -73,7 +72,8 @@ registerBlockType( 'gutenberg-boilerplate-esnext/hello-world-step-03', { attributes: { content: { type: 'array', - source: children( 'p' ), + source: 'children', + selector: 'p', }, },