Tutorial on custom block that stores post meta

[ryanwelcher]

Discussed in https://github.com/WordPress/developer-blog-content/discussions/35

^{Originally posted by **justintadlock** December 9, 2022} One of the major hurdles that plugin authors need to overcome, particularly in client work and alongside custom post types, is to learn how to create blocks that store their data as post metadata instead of within the `post_content` field. I don't think there are a ton of resources around this in the wild, but the Developer Blog would be an ideal place to introduce this to more extenders. Right now, this topic idea is really rough, but I want to leave it open to input on what we would want to see come out of such a tutorial.

[wpfangirl]

I have several client sites that rely on one form or another of post meta for custom post types. Many of these custom fields were created by ACF; some come from plugins. It's important to have things like dates and speakers for events, or authors for books, or prices for products, in query loops for those post types, and so far I've found only a couple of tutorials on how to do it. (And not had time to try them.)

I've built ACF blocks before, but those actually store the field info in the post content like other blocks, and I'm not aware that I can use them to access existing ACF fields in post meta. That means they won't work in query loops.

Also, I'm looking at the problem more as someone who builds themes than as someone who builds plugins: the challenge is discovering post meta that's already in the database and displaying it in the theme.

[justintadlock]

Potential related use case that came up via Slack: https://wordpress.slack.com/archives/C03RL47B3S8/p1673457453872079

[carstingaxion]

Hello everybody,

I just read on Developer Blog – Editorial meeting: February 2, 2023 – Make WordPress Core about this idea and instantly wanted to join the party. :tada:

I recently published a template for the create-block package to spin up a (starting point for a) dynamic block to show specific postmeta as a dynamic block. I'm in the same situation like @wpfangirl and tried to create this template as a more DRY approach to my repeating problem. You can find it at carstingaxion/postmeta-block-template and use it via the --template flag as usual.

npx  @wordpress/create-block --template @carstenbach/postmeta-block-template

Even that I didn't have any issues published for this package, i had some ideas for improvement in mind. I thought about packing 2 variants into the template. One that generates a block with a non-editable field, usable for showing calculated or aggregated post_meta which is not intended to be changed by an editor. And anotherone, similar to the current state, that creates a more dynamic editable block, usable for more semantic post_meta, like mood while writing or the premiere-date of theater production.

I could imagine writing a kind of article around this topic and the further development of either my package as also the blocks it creates.

What do you think; would this propably fit together?

Btw. I would really appreciate to read your feedback on the mentioned template. ;)

[carstingaxion]

As more I think about this topic and the troubles I had to overcome in the last couple of months regarding to post_meta, I would like to write about it.

What came into my mind since yesterday and in no explicit order:

• When to go for post_meta instead of just using block attributes? And when not. With some insights from different best-practices flying around, why it's sometimes better to choose custom taxonomies instead of post_meta for performance reasons. Maybe as a kind of introduction to post_meta at all.
• How to enable authors to edit different types of post_meta with the built-in frameworks, we already have, thanks to @wordpress/components and others. This is for sure a section to make a point against using any kind of third-party frameworks (in the future) to handle post_meta within WordPress, but instead to rely on the many, many new and pretty cool core packages. I've been using plugins and libraries like Metaboxes, CMB2 or ACF in the past, but haven't had a need for any of them in the last two years of day-2-day work (on new projects).
• Things I learned while creating custom blocks for different semantic types of meta data, from the UI elements available, the storybook, formatting the data based on author preferences using block attributes or even on localising such data.
• I'd like to share the joy of creating custom blocks, the user-friendly shortcodes alternative.

You see, many ideas in no order, with propably too many grammatical vodoos.

Also I realiced today that @ryanwelcher removed the flow: needs writer label, which I overlooked yesterday. In case he or someoneelse is going to write this article, I would be happy to share some ideas.

[justintadlock]

Hi, @carstingaxion. Yes, Ryan is already writing this specific article. However, there's always the chance that there's room for other angles or alternative examples related to post metadata and blocks. One thing you could do is wait to see what he's written, and if you think you have another approach that would work well for the subject matter, open a new topic idea. Feel free to reach out the #core-dev-blog Slack channel too. We definitely want more folks contributing.

The feedback you've added is great too.

[wpfangirl]

As more I think about this topic and the troubles I had to overcome in the last couple of months regarding to post_meta, I would like to write about it.

What came into my mind since yesterday and in no explicit order:

• When to go for post_meta instead of just using block attributes? And when not.

Ah, the content decision tree! I've thought of writing something about that myself, @carstingaxion. When do you want a custom post type vs. a block vs. a taxonomy? One of my deciding factors is whether I'm going to need to display the information in more than one place, and in more than one way.

[ryanwelcher]

Thanks for all the great ideas/feedback here!

This is clearly a very deep topic and it may even make sense to do a series on working with Post Meta.

My current approach is to start with how a block can read from and write to native post meta ( ACF is a different animal as it stores its meta in a different place than native WP meta ). At a high level, this first article will cover the following topics/concepts:

1. A brief introduction to scaffolding a block using the @wordpress/create-block package both to create a full plugin and using the--no-plugin option to add to an existing one.
2. High-level discussion on when to use post meta vs block attributes ( Does it need to be meta? )
3. Introduce a simple use-case: A custom Testimonial block that writes the testimonial text to post meta on a Products post type.
4. Exposing the post meta to the REST API
5. Covering the usesContext property of block.json to retrieve the current post ID.
6. Introduce the useEntityProp hook used to read and write to post meta.
7. Bonus - Reading from ACF meta. This is possible and is actually pretty straightforward. Writing back to the meta is also possible as well but is much more involved and I am not sure it fits with this tutorial.

Based on the above, the reader will be able to create a custom block that can read from and write to post meta. This block can then be used as a standalone block in the content in the Post Editor or Site Editor as well as part of a template for the Query Loop block.

[ryanwelcher]

@bph @justintadlock Draft post is ready for review here. I have not added the code snippets to the doc but have them prepped.

[justintadlock]

I have gone through the first review and left comments. I think it would've been more helpful to see the code snippets, though, so that I could more easily follow along with the reader. But, we can go through an additional tech review later (useful for catching any potential code typos).

Overall, I'm really looking forward to seeing this go live! 🚀

Some additional notes:

You, not we:

I'm often guilty of this, but it's best to be talking directly to the reader. This conversational tone will work much better. I only outlined the first instance of this, but it should be updated throughout. I'm happy to go through and mark them all if you want me to.

Images:

Give a few screenshots of what some of this looks like in the editor. It'll help the reader know if what they're doing looks like what you're teaching. Build their confidence with imagery.

[ryanwelcher]

@justintadlock I've updated the draft based on your notes. Would you mind having another look when you can?

I'm going to put a gist together for all of the snippets so they can be reviewed as well. I'll follow up with a link to that here.

Give a few screenshots of what some of this looks like in the editor. It'll help the reader know if what they're doing looks like what you're teaching. Build their confidence with imagery.

Great idea! I'll gather those as well.

[justintadlock]

@ryanwelcher - Great job on that! Still seeing a few "we" instances, but you can Cmd + F for those in the doc.

[ryanwelcher]

🤦 ok NOW I've addressed them all. Thanks again for the review.

[bph]

@ryanwelcher

I'll wait with the 2nd review until you post the draft on the blog with your code examples and illustrations/screenshot.

Here is also the pre-publish check list for your reference:

• [x] Post Title in Sentence case
• [x] Are Category or Categories selected?
• [x] Are Tags identifies?
• [ ] Is there an Excerpt?
• [x] Props added?

Please share the Public Post Preview link here, when ready.

[ryanwelcher]

@bph @justintadlock here is the preview for the draft - https://developer.wordpress.org/news/?p=891

[justintadlock]

I've reviewed the code. It all looks pretty good to me and easy to follow. The one thing I might add is the sanitize_callback argument for the register_post_meta() call for good measure: https://developer.wordpress.org/reference/functions/register_post_meta/

There were also a couple of code blocks in the "Modifying the block.json" section with no language associated with them, so they aren't getting the syntax highlighting.

Other than that and any other feedback, it looks good to go.

[bph]

I also went through the code examples and everything should work well.

I made tiny corrections:

Be sure to go to the Plugins page and enable it before continuing.

changed to 'activate it' - to stay close to WordPress lingo

add the following CSS to the style.css file

Changed it to style.scss - there is not style.css in the built plugin directory.

My first draft of the excerpt: "Learn how to create a block that stores information in post meta, how to retrieve it from the database, and how to render it on the front end. In addition, you find an example on how to use the create-block to scaffold a dynamic block. "

@ryanwelcher you might want to edit it.

Furthermore, code blocks need a title when there are more than one under one heading.

Other than that, it's all ready to go.

[ryanwelcher]

I also went through the code examples and everything should work well.

I made tiny corrections:

changed to 'activate it' - to stay close to WordPress lingo

Changed it to style.scss - there is not style.css in the built plugin directory.

Great catches, thank you!

My first draft of the excerpt: "Learn how to create a block that stores information in post meta, how to retrieve it from the database, and how to render it on the front end. In addition, you find an example of how to use the create-block to scaffold a dynamic block. "

Great start, I'll get this updated.

Furthermore, code blocks need a title when there are more than one under one heading.

👍

[ryanwelcher]

@justintadlock @bph I've made the requested changes. Assuming there are no other changes, am I OK to publish?

[ryanwelcher]

Changes requested on Slack from @fabiankaegy

Just reading through the post meta article and really like the way you wrote about it :slightly_smiling_face: Great Job! I have one small piece of feedback (sorry didn’t see it sooner in the review phase) In your PHP frontend code you have this here: global $post; $testimonial = get_post_meta( $post->ID, 'testimonial', true ); If you change that to $testimonial = get_post_meta( $block->context['postId'], 'testimonial', true ); It would also automatically work within the query block since it is getting the correct post id :slightly_smiling_face: And in your JS you are already using the context and showing the usesContext way :slightly_smiling_face: (wasn’t sure where else to provide this feedback so please let me know where else I should add things like this in the future)

[bph]

Published: Creating a custom block that stores post meta

[ryanwelcher]

Closing this out now that it's been published