Convert Shortcodes to blocks

[bph]

by @jonathanbossenger

Case study of how to approach shortcut conversion, using Seriously Simple Podcast plugin for some "real world" examples, that now has both, regular blocks and the dynamic rendering option, based on the requirements of the block.

[jonathanbossenger]

Brain dump

1. Intro to React
2. Intro to Webpack and how it works with your current setup
3. Not every shortcode should be a block!
4. Intro to create-block
5. Converting simple shortcodes that use default block edit/save functionality
6. Converting shortcodes that make more sense to use the dynamic block rendering
7. Creating custom components to reduce redundancy
8. Using apiFetch to get WP data to power blocks
9. Using core-data to get WP data to power blocks
10. Where to find information (navigating the block editor handbook)

[jonathanbossenger]

@bph I have asked folks to comment on this ticket with comments/ideas/suggestions of things to cover, in the hopes that it will help uncover the hurdles folks are experiencing. I'll probably leave this open for about 2 weeks, and then get cracking once I've gathered whatever feedback I get.

[alanef]

Looking at it the other way around, every block should have a shortcode!

Why? Because of the dozen or so popular page builders that all understand shortcodes, but don't understand blocks. ( Or maybe, encourage all page builders to understand blocks / incorporate Gutenberg?)

Assuming the former, as a plugin dev having two code lines one for blocks and one for shortcodes is a hard thing, but having three code lines, one for shortcodes, one for block editor and one for block display is even worse.

This is just random thoughts, not structured.

My path has probably been a typical PHP/jQuery path of many devs in this space, so a jump into REACT for just the editor is a steep learning curve which I'm maybe 6 months into and only scratching the surface.

Shortcodes are dead easy, just a couple of lines of PHP with a text editor and you are up and running.

Blocks are harder unless you have a local dev env, node / npm installed then create_block is useful, but a as plugin dev it was no use until the recent --no-plugin option was released.

But there still is the unanswered question in my head 'What is the appropriate architecture for a block/shortcode plugin without duplicating functionality across the code lines'.

[justintadlock]

I have asked folks to comment on this ticket with comments/ideas/suggestions of things to cover, in the hopes that it will help uncover the hurdles folks are experiencing. I'll probably leave this open for about 2 weeks, and then get cracking once I've gathered whatever feedback I get.

I have converted several shortcodes to blocks, and the one thing I still struggle with is getting data, such as posts and users. For some reason, I never wrote a simple shortcode. :)

Here are some examples that I painstakingly cobbled together:

• Post types: https://github.com/x3p0-dev/x3p0-archives/blob/master/resources/js/block/edit.js#L33
• Posts: https://github.com/x3p0-dev/x3p0-archives/blob/master/resources/js/block/edit.js#L83
• Users: https://github.com/x3p0-dev/x3p0-list-users/blob/master/resources/js/edit.js#L42

When I was building those bits of code, I never felt like there were any good resources for getting the data I needed on the JS side (something that has always felt super easy in PHP).

"Getting data and doing something with it" is probably one of the most important things for plugin developers, so any extra focus in that area helps.

[andrewlimaza]

I have asked folks to comment on this ticket with comments/ideas/suggestions of things to cover, in the hopes that it will help uncover the hurdles folks are experiencing. I'll probably leave this open for about 2 weeks, and then get cracking once I've gathered whatever feedback I get.

The main hurdle is the tooling around here and not fully understanding webpack. We tweak the wordpress/scripts webpack to adjust the entry and output points to fit our file structure. What we need is to output to assets/js and entry point would be /blocks (with various subfolders).

Right now, it nukes everything in the assets/js whenever you use wp-scripts start or build. Not sure if this is a NPM version thing or if there's a setting we can use to keep pre-existing files (other .js files for plugin frontend/admin etc) and just rebuild the files we need (i.e. blocks.build.js).

Also a standardized file structure for blocks (within a plugin) would help us, this is something we're working on for our own team (not paving the way for WP) but with the ever evolving tools and understanding of blocks we need to neaten this up internally as we built blocks before wp-scripts was a thing or we just didn't know about it (I can't remember 5 years ago what was our thought approach). We have moved over to wp-scripts ever since which made things easier but still gets confusing to troubleshoot this when things don't work. Our goal now is to to move to a set file structure and webpack config in upcoming plugins that already have shortcodes and other /js files. We have made some workarounds but I don't feel that these are ideal.

Here is an example where we adopted blocks early on and you may see the file structure we'd typically work with - https://github.com/strangerstudios/paid-memberships-pro (Most of our shortcodes and pages have turned into blocks to make working with our plugin easier).

+1 for justin's comment, getting data wasn't easy and often confusing (when coming from PHP to REACT).

[jonathanbossenger]

I have converted several shortcodes to blocks, and the one thing I still struggle with is getting data, such as posts and users.

TIL about the core-data package! I just ended up using apiFetch package and DIYing it. Might be useful to cover both options

[bph]

@jonathanbossenger
I finally looked over the outline, and 1 & 2 can be taken care of by linking to existing pieces, like workshops and documentation. There might even be something in the Block Developer course introduction. Not every blog post can start at the beginning. I would start in the meat of the matter, and guide readers to the existing documentation for deeper dives.

Start with 3. Not every Shortcode should be a block!
Even create-Block has received lots of attention in other tutorials (Docs, learn). A link might suffice here as well.

Good luck!

Thanks for commenting also @andrewlimaza - That's in interesting observation. Come to think it if, I am also confused about how Webpack and WordPress packages interact, and it would be a great separate blog post for the new site. What do you think?

[jonathanbossenger]

@bph this sounds like a good plan.

I'd also be happy to write the "how Webpack and WordPress packages interact" blog post as a sort of "follow-up" once this post is published.

[jonathanbossenger]

General outline

1. Not every shortcode should be a block!
2. Intro to create-block
3. Converting simple shortcodes that use default block edit/save functionality
4. Moving layout from shortcodes to the presentation layer
5. Converting shortcodes that make more sense to use the dynamic block rendering
6. Creating custom components to reduce redundancy
7. Using apiFetch to get WP data to power blocks
8. Using core-data to get WP data to power blocks
9. Where to find information (navigating the block editor handbook)

[bph]

"how Webpack and WordPress packages interact"

@andrewlimaza @jonathanbossenger I created a discussion under ideas to see what other people would need to learn in that regard. Please share with your colleagues and network so people can chime in.

So this issue can be about @jonathanbossenger's blog post moving forward.

[jonathanbossenger]

Update: This weekend I completed the first rough draft of this post. During the course of this week, I plan to review/edit the post, create relevant screenshots, and test my code examples. I'm working towards having this ready for review by the end of this week.

[jonathanbossenger]

Quick update here, I've had to put this on hold for a bit, as I need to wrap up my second block theme course (by end of this week). I hope to pick it up and have it ready for peer review next week.

[bph]

@jonathanbossenger Thanks for the update!
We need to clone you, don't we 🤣
Can hardly wait for both, the Part 2 on the Theme course and the article!

[jonathanbossenger]

We need to clone you, don't we 🤣

That wouldn't work, because I'd just get the clone to do my work, and I'd spend all day doing other things...😁

[jonathanbossenger]

Update, I had some time this week to work on the draft, and it's almost there

https://gist.github.com/jonathanbossenger/e0f3337325a72fa5ee1c2efa9f9696e1

I need to write the final section, add some images, and do a final review, which I should get done next week.

[bph]

That sounds great.

When you feel you are ready for review, could you please

• double-check it against the guidelines
• post it to the blog in draft,
• enable public preview, and
• share the public preview link in a comment here.

Looking forward to reading your post 👏

You should have access to the blog already. Let me know if there is trouble. 😋

[jonathanbossenger]

Picking this up this week.

[jonathanbossenger]

This post is now ready for review https://developer.wordpress.org/news/?p=520&preview=1&_ppp=f9621ab6b7

[nalininsbs]

In progress: @bph doing first review, @abhansnuk doing second review. Adding this to test my GitHub access on this as there was a problem earlier with a laptop change. I had volunteered to read some of the beginner items. Nalini

[bph]

Feedback / Review

This is a great hands-on tutorial. The discussion of when and when not to create a block for short code functionality is fabulous. From the depth of the content I would categorize this not as a beginner tutorial, so keeping the getting started part short would be best. At the moment, it does a bit too much before it actually gets to the meat of the matter. It is an excellent journey description from your duplicate code to Custom Components, great use case for JSX. I really enjoyed the reading and learn something.

I have a few suggestions on how to streamline the beginning and the end of things. I might be a little overzealous in suggestions on where to cut. Please don't take it the wrong way. I think this tutorial is fantastic in what it teaches, and it will be successful if aimed at users who have a more advanced knowledge, and assume the reader already have beginner knowledge.

Getting started

You could shorten the runway, so to speak, in the getting started section, by referring to two official sources.
Learn WordPress Course Introduction to Block Development: Build your first custom block
The post on the Developer blog: A PHP developer’s guide to getting started with block development
These changes might take care of the sections "Learning React" and the "Intro to Create Block", and will mean the reader will be able to jump right into your projects. I really would think you post wins big time when you shorten the 'preliminaries'.

Video Embedding

Instead of embedding the create-block video taking away too much space from the heart of the post, suggest just linking to it. The other links should go in the Resources section.

Not every short code should be a block

You should have the discussion on “Not every shortcode should be a block!” after the ‘Getting Started’ piece.

The example for not creating a block for the [time] short code is a great one, and it could use a bit more detail. It would gain some immediate insight for the reader if you add a front end view of this particular short code, as it would show that's rendered inline in a paragraph. Then you could mention that kind of inline rendering is not possible with Gutenberg right now. There are some first attempts to find a way to make those dynamic strings possible without using a short code, but it's not available yet. If someone wants to dive into this discussion, it is very fascinating Discussion, with a draft PR for implementation.

External Links

"For my own purposes, I took the React for Beginners course by Wes Bos".

External Link policy is for now really strict. You could link to React itself and its introduction tutorial. https://reactjs.org/tutorial/tutorial.html

Links need to have a descriptive text (title of the post/document) + URL not just the blank urls.

As mentioned, the videos should go into the Resource section. I would think you wrote most of what you said in the video also in this post, and if not, you might include it in your post.

Visuals beyond Code

The tutorial would gain a lot if you could also show editor views on your examples in addition to the code examples. That way the reader gets a mental image to see a difference between classic editor short code view and block editor view.

Code Blocks

If you select a language from the Code block sidebar, you get some nice color coding added to your code examples. You could add the “Example HTML” as Title to the code block settings.
The screenshot is from your post after I adjusted the code blocks.

Recommendation is if you have under the same heading more than one code example, you should add a title to each code block.

Resources to learn more

"Where to find help" - Maybe retitle to "Resources to learn more"
The links to get started are already covered at the beginning, but it doesn't hurt to repeat them.

Many Gutenberg contributors are sponsored full time to work on Gutenberg, and so I’d recommend trying to reach out to one of them via the Make WordPress Slack. I’m sure they’d be happy to help.

The #core-editor channel is not really meant for developer support. You can also offer to comment on the post with questions, that's immediate, and we can handle that.

Discussions on the Gutenberg Repo are a good place, or StackExchange.

[jonathanbossenger]

Thanks for the feedback @bph will review and implement

[jonathanbossenger]

Hello @bph and @abhansnuk I've completed the update to the post based on the feedback, so this is ready for the second review.

[abhansnuk]

Thanks @jonathanbossenger could you share a public preview link please? The earlier one has expired. Thanks. Looking forward to reading this and thanks for incorporating all the comments.

[jonathanbossenger]

Sure, here is the new preview link https://developer.wordpress.org/news/?p=520&preview=1&_ppp=6ca85b2512

[bph]

I took another look, and we are almost ready to publish.

• convert the links listing mere URL to the title of the page

Here is the pre-publish check list.

• Post Title in Sentence case
• Are Category or Categories selected?
• Are Tags identifies?
• Is there an Excerpt?
• Props added? (right aligned, italics.)

The tips and guidelines for writers you already read, so this is just a reminder.

this sentence is a bit awkward. "Through my connections in the WordPress community, I was able to make connections with a few folks who were willing to help me answer specific questions."

only marginally better, but maybe this works?
" I am grateful for my many friends in the WordPress community, who helped me answer specific questions."

Please check the excerpt, and update the props section...

[abhansnuk]

That amendment by @bph would be my suggestion too, it keeps the essence of what is said. I can do the second review in a few hours depending on another doc I am looking at on the release, and if not in my tomorrow afternoon (UTC).

[jonathanbossenger]

Published https://developer.wordpress.org/news/2023/03/converting-your-shortcodes-to-blocks/

[juanmaguitar]

@jonathanbossenger could we update the post to include https://learn.wordpress.org/course/converting-a-shortcode-to-a-block/ ?

[jonathanbossenger]

@juanmaguitar good idea, done! ✅