Add a tutorial for creating a meta block

[mkaz]

Description

This tutorial walks a developer through create a meta block, which is a block that stores data to post meta. It includes showing how to use a template to auto include the meta block so it is not hidden.

Fixes: #12621 #7696

Preview at: https://github.com/WordPress/gutenberg/tree/docs/metabox/tutorial/docs/designers-developers/developers/tutorials/metabox

Types of changes

Documentation.

[swissspidy]

I think it's worth adding a PHP render callback for the block to show people how to get the meta data in a block.

[mkaz]

I think it's worth adding a PHP render callback for the block to show people how to get the meta data in a block.

@swissspidy Do you mean for using meta data in a different block? I do want to show a way to use the data somewhere else, but I have not been able to come up with good example case.

[mkaz]

@swissspidy I added an extra step showing how to use the post meta both in a block and in a filter. Take a look and let me know if that addresses your concern. Thanks!

[mrleemon]

So, does one have to create a new separate block for every different meta field? On custom post types with many meta fields we'll end up creating many very similar blocks with the only difference being the meta key used.

[swissspidy]

No, a block can contain an infinite number of such fields.

[mkaz]

@mattyrob if you can share your code that you have I can try to help troubleshoot, and update the tutorial to fix any bumpy spots. You can either post here in the comments or if a Github Gist is easier, anyway that works for you.

I've walked through and tested again and the code is working for me, but then I made it so that tends to happen. :-)

[mattyrob]

@mkaz

Thanks for reaching out, I think it got it pretty much working in the end - the 2 things that need clarification for me are this (feel free to correct if I'm wrong).

1/ When making the register_meta() function call and 'auth_callback' parameter needs including otherwise the editor user doesn't have permission to update the meta data field.
I'm using:

auth_callback' => function() {
	return current_user_can( 'edit_posts' );
},

2/ In my plugin I load specific hooks on the admin side or the frontend, documentation I read says that REST API hooks need to go on the frontend, this doesn't work well in the new editor (Gutenberg) as the data fields are not accessible in admin (if I get change I'll try to find that documentation - it may need updating).

[swissspidy]

Why not register_post_meta?

[mkaz]

I find register_post_meta to be slightly more complicated since the syntax requires passing an empty string in for the post type to cover all types.

Whereas using register_meta() and passing in post covers all post types by default.

I don't feel that strongly about it, so could switch easily.

[swissspidy]

When making the register_meta() function call and 'auth_callback' parameter needs including otherwise the editor user doesn't have permission to update the meta data field.

Only if your meta field is protected.

If you look at register_meta(), you can see that auth_callback defaults to __return_true unless the meta key is protected (starts with an undersccore), in which case it's __return_false` and you need to pass your own callback.

[mrleemon]

Will you add the ES6 version of the following code?

https://github.com/WordPress/gutenberg/blob/docs/metabox/tutorial/docs/designers-developers/developers/tutorials/metabox/meta-block-3-add.md

[mkaz]

In f346699 I updated to include a section regarding keys starting with underscore and how to work with that.

[mkaz]

@mrleemon I do not plan to include an ES6 version, ES5 works without the build step and is easier to explain the concepts with a simple change/reload and not worrying about builds running/breaking and other issues unrelated to the core of the tutorial.

If you prefer ES6 syntax, converting should be straight-forward and a good exercise to confirm you understand the material.

[swissspidy]

Most docs in the handbook have both ES5 and ES6 code examples, don't they?

[oandregal]

Rebased from master to update TOC and Manifest. Pushed some changes to update links, move the image to the assets folder and update the meta field name in the examples.

[chrisvanpatten]

A few small tweaks; more TK

[chrisvanpatten]

Final set of tweaks. Love this tutorial; nice work @mkaz!

[mkaz]

Thanks @chrisvanpatten and @nosolosw I've incorporated all the feedback, I appreciate the assist on making this a great tutorial.

[chrisvanpatten]

👍 Props @mkaz this is great!

[youknowriad]

I'm loving these tutorials. Thanks.