From f2a264141b925f2af7020589f47e3ff41204d657 Mon Sep 17 00:00:00 2001 From: Aaron Jorbin Date: Mon, 19 Feb 2018 16:15:34 -0500 Subject: [PATCH 1/3] Use 03-editable-esnext to introduce people to esnext If you have not been exposed to esnext, it's easy to get lost. Concepts like Destructuring assignment and arrow functions can be foriegn. This adds inline documentation with esnext terminoly and links to mozilla documentation. Additionally, Gutenberg specific concepts are linked to in order to assist with understanding how to build your own blocks. --- 03-editable-esnext/block.js | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/03-editable-esnext/block.js b/03-editable-esnext/block.js index 1a8477d7..5a375ab0 100644 --- a/03-editable-esnext/block.js +++ b/03-editable-esnext/block.js @@ -1,23 +1,45 @@ +// `const` is for creating block scoped variables that can not be reassigned. +// see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const +// +// These are using Destructing Assignment which can be used to unpack properties from an object +// see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment const { __ } = wp.i18n; const { registerBlockType, Editable, source: { children } } = wp.blocks; +// registerBlockType is the base function for registering a block +// see: https://wordpress.org/gutenberg/handbook/block-api/#register-block-type registerBlockType( 'gutenberg-examples/example-03-editable-esnext', { + // the displayed title in the block selector title: __( 'Example: Editable (esnext)' ), + // this can be any of WordPress Dashicons, or a custom svg element. icon: 'universal-access-alt', + // The category where the block will live in the block selector category: 'layout', + // this blocks structrued data + // See https://wordpress.org/gutenberg/handbook/block-api/attributes/ attributes: { content: { + // the data type we are storing type: 'array', + // source and selector combine to dictate how to get this content source: 'children', selector: 'p', }, }, + // This uses arrow functions which inherit `this` from it's parent. + // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions + // + // The edit function describes the structure of your block in the context of the editor. + // see: https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#edit edit: props => { const { attributes: { content }, focus, className, setFocus } = props; const onChangeContent = newContent => { props.setAttributes( { content: newContent } ); }; + // We are returning JSX which babel will convert for us due to the use of `babel-plugin-transform-react-jsx` + // Intro to JSX: https://reactjs.org/docs/introducing-jsx.html return ( + // see: https://wordpress.org/gutenberg/handbook/block-api/editable-api/ ); }, + // The save function defines the way in which the different attributes should be combined into the final markup + // see: https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#save save: props => (

{ props.attributes.content } From cc50d18efdba16bd265bc1d77c0d4d0683d2ea40 Mon Sep 17 00:00:00 2001 From: Aaron Jorbin Date: Sat, 24 Feb 2018 16:41:52 -0500 Subject: [PATCH 2/3] update docs based on feedback --- 03-editable-esnext/block.js | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/03-editable-esnext/block.js b/03-editable-esnext/block.js index 5a375ab0..20bf7272 100644 --- a/03-editable-esnext/block.js +++ b/03-editable-esnext/block.js @@ -13,25 +13,34 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', { title: __( 'Example: Editable (esnext)' ), // this can be any of WordPress Dashicons, or a custom svg element. icon: 'universal-access-alt', - // The category where the block will live in the block selector + // The category where the block will live in the block insertor + // Possible values can be found at https://wordpress.org/gutenberg/handbook/block-api/#category category: 'layout', - // this blocks structrued data + // this blocks structured data // See https://wordpress.org/gutenberg/handbook/block-api/attributes/ attributes: { content: { // the data type we are storing + // See http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.1.1 type: 'array', - // source and selector combine to dictate how to get this content + // source dictates how to get this content + // HTML-based sources will have a selector source: 'children', selector: 'p', }, }, - // This uses arrow functions which inherit `this` from it's parent. - // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions - // - // The edit function describes the structure of your block in the context of the editor. - // see: https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#edit + + /** + * The edit function describes the structure of your block in the context of the editor. + * This represents what the editor will render when the block is used. + * @see https://wordpress.org/gutenberg/handbook/block-edit-save/#edit + * + * @param {Object} [props] Properties passed from the editor. + * @return {Element} Element to render. + */ edit: props => { + // The above uses arrow functions which inherit `this` from it's parent. + // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions const { attributes: { content }, focus, className, setFocus } = props; const onChangeContent = newContent => { props.setAttributes( { content: newContent } ); @@ -40,7 +49,7 @@ registerBlockType( 'gutenberg-examples/example-03-editable-esnext', { // Intro to JSX: https://reactjs.org/docs/introducing-jsx.html return ( // see: https://wordpress.org/gutenberg/handbook/block-api/editable-api/ - ); }, - // The save function defines the way in which the different attributes should be combined into the final markup - // see: https://wordpress.org/gutenberg/handbook/block-api/block-edit-save/#save + + /** + * The save function defines the way in which the different attributes should be combined + * into the final markup, which is then serialized by Gutenberg into `post_content`. + * @see https://wordpress.org/gutenberg/handbook/block-edit-save/#save + * + * @return {Element} Element to render. + */ save: props => (

{ props.attributes.content } From 342ba15486fecfee32920100e0c3c89a3a387821 Mon Sep 17 00:00:00 2001 From: Aaron Jorbin Date: Sat, 24 Feb 2018 16:44:07 -0500 Subject: [PATCH 3/3] remove wp.blocks.source --- 03-editable-esnext/block.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/03-editable-esnext/block.js b/03-editable-esnext/block.js index 20bf7272..5b5361d4 100644 --- a/03-editable-esnext/block.js +++ b/03-editable-esnext/block.js @@ -4,7 +4,7 @@ // These are using Destructing Assignment which can be used to unpack properties from an object // see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment const { __ } = wp.i18n; -const { registerBlockType, Editable, source: { children } } = wp.blocks; +const { registerBlockType, Editable } = wp.blocks; // registerBlockType is the base function for registering a block // see: https://wordpress.org/gutenberg/handbook/block-api/#register-block-type