When Block Styles Are Not Enough: Extending Blocks in Themes

[bph]

Discussed in #130

^{Originally posted by justintadlock June 12, 2023}
Tutorial proposal:

One of the oft-repeated issues with WordPress' block styles system is that users can only add one style to a block at a time. More on this Gutenberg ticket: WordPress/gutenberg#14598

There are pros and cons to this system:

• Pro: It keeps highly distinctive styles from clashing.
• Con: You can't mix and match simpler or smaller design pieces that wouldn't clash.

There has to be a middle ground...

How to combine block styles?

That is the question that has frustrated many developers. For example, suppose you had a "Large Text" style and a separate "Gradient Outline" style for the block. Do you create a third style named "Large Text with Gradient Outline"? That is what some devs have resorted to, but it is a slippery slope with each new style you add. And, you would never do this in a solid design system.

At the end of the day, a block style is nothing more than a simple class that uses a standard .is-style-{$slug} naming scheme. The reason this is great for themes is that it doesn't negatively impact user content if/when users switch themes.

And this is (relatively) simple to recreate.

On the most low-effort DX end of the scale, you just have users input custom classes into the "Additional CSS Class(es)" box and call it a day. But, that makes for a poor UX.

On the other end of the spectrum, you build custom controls and let the user interact with them through the interface. Unlike custom blocks or plugins that add custom attributes, this system would use CSS classes under the hood. That means it also plays nicely with the WordPress theme review guidelines.

I've created several solutions in the past couple of weeks for testing this system. It works really, really well.

For example, here's a "Gradient Outline" picker that I put together:

Teaching theme authors block editor JavaScript

There are two things at play:

1. Theme authors must first learn how to set up the @wordpress/scripts package and integrate it into a theme. AFAIK, there is no documentation aimed directly at theme dev, but it definitely works.
2. Introduce theme authors to concepts that would typically fall under "block" development.

This is potentially a two-part series because both of the topics could be relatively beefy on their own.

[justintadlock]

I'll be working on this series here: https://docs.google.com/document/d/12A8JzvVdEGDpiK7OYS_RnaHFXAXE32FV2u-jtXxPfnQ/edit?usp=sharing

[justintadlock]

Part 1 is now ready for review: https://docs.google.com/document/d/12A8JzvVdEGDpiK7OYS_RnaHFXAXE32FV2u-jtXxPfnQ/edit?usp=sharing

[marybaum]

On it as soon as we hit the hotel, in about four hours. We are touring the mountains in CO until Thursday ⛰️ MB... from my phoneOn Jul 17, 2023, at 11:13 AM, Justin Tadlock ***@***.***> wrote: Part 1 is now ready for review: https://docs.google.com/document/d/12A8JzvVdEGDpiK7OYS_RnaHFXAXE32FV2u-jtXxPfnQ/edit?usp=sharing —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[justintadlock]

Thanks, Mary. Make sure to take some time to relax while you're out there.

---

Side note: I switched over to writing from a first-person POV for this one. That's a bit more along the lines of my normal style. I can always change it back to only using "you" statements if necessary, but I wanted to see how this worked for a Dev Blog article.

[marybaum]

I’m sure that’s fine! I’m all for the first-person singular, because A—your own experience is incontrovertible B—there’s an old saw that runs: people often don’t care what you know until they know how much you care. I’ll amend that to … until they know why you care and therefore why they should.That’s why stories are so compelling, imho.Here are two shots from this morning, btw! ... from my phoneOn Jul 17, 2023, at 2:28 PM, Justin Tadlock ***@***.***> wrote: Thanks, Mary. Make sure to take some time to relax while you're out there. Side note: I switched over to writing from a first-person POV for this one. That's a bit more along the lines of my normal style. I can always change it back to only using "you" statements if necessary, but I wanted to see how this worked for a Dev Blog article. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you commented.Message ID: ***@***.***>

[marybaum]

Done!

[bph]

• Did a first read on getting in the mindset. I offered minor suggestions.
• Excellent description of the problems to solve, one at a time.
• I won't have time to follow along with the instructions, that would need to wait until later this week. (don't wait for me to publish, though)
• it would use a list of the next parts at the end and a consolidated list of resources listed around the post.

[justintadlock]

Thanks, @marybaum and @bph for the awesome feedback!

I won't have time to follow along with the instructions, that would need to wait until later this week. (don't wait for me to publish, though)

@juanmaguitar walked through the steps already, so an extra walkthrough shouldn't be necessary, unless you just want to.

it would use a list of the next parts at the end and a consolidated list of resources listed around the post.

The last paragraph tells what Part 2 and Part 3 will cover. I'll round up all of the resources and add a section for them.

[justintadlock]

This is ready for a final review before publishing. Public preview: https://developer.wordpress.org/news/?p=1706&preview=1&_ppp=3972d053e8

---

IMPORTANT NOTE TO SELF: Add image alt attributes.

[juanmaguitar]

Node and npm: You must have Node.js and npm installed on your local machine to follow along. The Block Editor Handbook has a guide on setting up your development environment.

I know I made a previous comment about providing a version for Node but as per this I think the version suggested in the Block Editor (v14) is to contribute to gutenberg (run tests and stuff) but this version is not really needed to run the scripts (any Node version should be fine to run the scripts)

So, I would remove The Block Editor Handbook has a guide on setting up your development environment. to make it easier for the readers.

[justintadlock]

Thanks for the final check, @juanmaguitar. I removed that bit but maintained the link in the resources section in case anyone wants to dive deeper.

[justintadlock]

Published Part 1 here: https://developer.wordpress.org/news/2023/07/beyond-block-styles-part-1-using-the-wordpress-scripts-package-with-themes/

I'll open a new ticket for Part 2.

[aplauche]

@justintadlock Thanks for the great series! Wanted to flag right now lesson 2/3 have links to the previous lessons, but lesson 1/2 do not have quick links to the next published lesson in the series. Would be nice to add maybe at the bottom of each?