4 April

Building a WordPress block theme is shortening my life expectancy

Throughout my (now quite long) career as a web developer, I have had many ups and downs. But I have never had as many stomach aches as I have in the last year, trying to wrap my brain around a steady stream of confusing, convoluted, counterintuitive and just downright inexplicable elements of building a theme from the ground up to work with Gutenberg, a.k.a. the WordPress Block Editor.

I’ve made some major progress over the course of the year, and my theme (in various stages of completion) is now powering multiple live client sites, with development ongoing for a few more. For the most part, now, I am finally at a stage where I feel like this is the right way to use WordPress going forward, rather than just reluctantly accepting that I have no choice in the matter.

But I still feel like Gutenberg does a lot of things the wrong way — most notably in its fundamental lack of separation between content and presentation. Yes, I am going to Old Man Yells At Cloud this. I know React is the new hotness and now everything needs to be done in ES6 (which I will forever call JavaScript), but the WordPress core team is throwing away some of the platform’s greatest strengths by abandoning this core component of how it (like pretty much any 2000s-era CMS) is built.

It may seem that I’m just an old curmudgeon who doesn’t want to learn React (I don’t), but it’s not just that. It’s that every aspect of this interface that has been designed to make it easier for average users to interact with — which, I think, it finally is, 5 years after it was unceremoniously forced on us — makes the process of developing for it harder, and more abstract.

There are two unrelated but connected problems with how things are going down here.

First, modern developers just love dependencies.

I get it. To an extent. Reusing tried-and-true code libraries instead of rolling your own all the time is smart. But that means you’re using code you probably haven’t looked at closely. You don’t really know how it works. It may have bugs, or it may have opaque features you don’t realize are there, or it may just have too much stuff bloating it, slowing down performance and making applications more brittle. Pile dozens of these dependencies together, and you’ve got a lumbering behemoth of code that no one in the world completely understands. And I truly do believe we are at a point where no one, at all, knows entirely how the current version of WordPress works. On top of that, any time you’ve got external dependencies, weird things can happen.

Second, Gutenberg is evolving so quickly that the documentation hasn’t kept up.

Gutenberg’s documentation is occasionally out-of-date, always incomplete, and it’s only getting worse.

I know writing documentation is tedious, and the web has never had good documentation. When I was in college in the mid-’90s and I wanted to learn HTML, I went to the campus computing department and asked them how I could go about learning HTML. They, seriously, just told me to download BBEdit. Which I did. And which didn’t help me learn HTML at all. (Although it is still the text editor I write all my code in, 29 years later.) So how did I learn HTML? View source. Because back then, you could do that.

I don’t expect to be able to just “view source” and learn how Gutenberg works. But since WordPress is open source software, and I have the files right here on my computer, I do think that when the documentation fails me, I should be able to poke around in the source code and find what I’m looking for.

Let’s get specific. As it happens, in my theme I’m addressing one of my earlier complaints above by using ACF Blocks. It’s been a rough road, but I’m starting to make really good progress. The only problem is, my styles aren’t getting applied. My CSS for the block isn’t loading in the Block Editor, and the Block Editor styles I’ve configured my block to support (colors, spacing, typography) via its block.json file are not showing up on the front end.

Well, what do I do about that?

Focusing on the front end first, I know that Gutenberg’s styles get applied courtesy of pithy CSS class names like .has-primary-background-color as well as HTML style attributes using CSS variables, like var(--wp--preset--spacing--80).

But if I look at the block attributes in the Block Editor’s comment tag, or the JSON or PHP array of style properties for the block, I see the same is formatted as such: var:preset|spacing|80

The quarter century of development experience in my old fart brain tells me that there must be a function or method, somewhere, that converts var:preset|spacing|80 into var(--wp--preset--spacing--80), and that I would be better off trying to find that function than writing my own.

Uhhh… OK. So how do I go about that?

ACF’s documentation for this feature is abysmal, which is kind of understandable, since the whole thing is a moving target that is changing rapidly (not to mention the organizational challenges that happen when the company that bought you out gets bought out itself), and the core WordPress documentation isn’t much better. So I’m left resorting to a scavenger hunt through the WordPress code. But it’s layer upon layer of 5-line functions referencing each other through a series of add_filter() callbacks.

As usual with my Gutenberg rants, I don’t have any solid conclusions to end on here. This whole post was mostly an exercise in working out that knot that was gnawing at my insides. At least I’ve done that. But I’m no closer to solving my problem. That’s probably because the real problem isn’t what I think it is. And it’s not going away.

All I know is, building a block theme — at least, for me, right now — takes way longer than building a classic theme. And I think that’s because my approach, one developer just cranking away, is not the model anyone in the core WordPress development community cares about, or possibly even comprehends existing. These days I’m not extremely confident about its continued viability myself.

Post script: I think I actually managed to find it, by using BBEdit’s multi-file search on this string: '|'

The method is: WP_Theme_JSON::get_property_value()

Of course, that doesn’t get called directly. It’s called in WP_Theme_JSON::compute_style_properties() which is in turn called by WP_Theme_JSON::get_block_classes() which itself is in turn called by WP_Theme_JSON::get_stylesheet() and then we’re getting too far afield, because that’s used to turn the theme.json file into inline CSS.

So I am guessing at this point that I probably should not use any of these methods. (Actually, I can’t because they’re all protected.) It really seems like this should be happening automatically, and either ACF Blocks are missing some key functionality, or I’m missing something about how ACF Blocks work (which I would blame on the lack of documentation).

Update (April 11, 2023): After I wrote this blog post, I also started a thread on the ACF forum, and there I was finally given an answer. Yes, there is a WordPress function for getting block wrapper attributes. It is even, um, named exactly what it should be. But as the fellow ACF user who responded with that enlightening bit of information even noted, it is incredibly difficult to find. The WordPress documentation does, to its credit, include most if not all (I mean, how would I actually know?) functions and methods, but the search tool is a joke.

Now I just need a 2-liter bottle of Shasta…

Today I woke up with a couple of nerdy ranking lists floating around in my head. I suspect these will get expanded into YouTube videos in the near future, but for now, just the straight lists. These are my personal rankings of all Rush albums, and all Metroid games.

Rush Albums Ranked

It’s probably worth noting here that I got seriously into Rush when I was a freshman in high school, in 1989, so there’s a definite before-and-after feel going here. The stuff that already existed when I got into them seemed mythic and eternal; the stuff after that is all “the new stuff” to me, even though the oldest of “the new stuff” is now 33 years old… but when it came out, the band’s first album was only 16 years old. (As was I.)

  1. Moving Pictures (1981)
  2. Signals (1982)
  3. A Farewell to Kings (1977)
  4. Permanent Waves (1980)
  5. Grace Under Pressure (1984)
  6. Hemispheres (1978)
  7. Clockwork Angels (2012)
  8. Counterparts (1993)
  9. Snakes and Arrows (2007)
  10. Power Windows (1985)
  11. Caress of Steel (1975)
  12. 2112 (1976)
  13. Vapor Trails (2002)
  14. Hold Your Fire (1987)
  15. Fly by Night (1975)
  16. Rush (1974)
  17. Feedback (2004)
  18. Roll the Bones (1991)
  19. Presto (1990)
  20. Test for Echo (1996)

I suspect many Rush fans would criticize my low placement of 2112 but I stand by it. I just don’t think it’s that great. I find the side-long suite on Caress of Steel to be more musically and conceptually interesting, and the other tracks on Caress are much more interesting than the utterly forgettable side 2 of 2112. I couldn’t even remember all of the songs. (After really straining my brain muscle I was able to come up with “Tears,” but I had to look at Wikipedia to remember “Lessons.”) I even prefer “I Think I’m Going Bald” to most of the filler tracks on 2112.

The Live Albums

Yeah, Rush had a bunch of live albums too. Earlier on in their career, they had a nice formula of four studio albums, then a live album. After Neil’s life fell apart in the late ’90s with the deaths of his wife and daughter, and the band’s future became more uncertain, they started releasing a live album after every studio album, plus some other archival material, and things got messy. I’m not even sure I’m accounting for all of them here. Anyway, here’s the list:

  1. A Show of Hands (1989)
  2. Grace Under Pressure Tour (recorded 1984, released 2009)
  3. Exit… Stage Left (1981)
  4. Rush in Rio (2003)
  5. R40 Live (2015)
  6. Time Machine 2011: Live in Cleveland (2011)
  7. Clockwork Angels Tour (2013)
  8. R30 (2005)
  9. Snakes and Arrows Live (2008)
  10. All the World’s a Stage (1976)
  11. Different Stages (1998)

I have to give special recognition to Grace Under Pressure Tour, because when the DVD of that was finally released in 2009, and I watched it, my jaw dropped. I suddenly remembered that I had seen it on TV in 1985 and was mesmerized by it, but that was the only time TV or radio ever exposed me to Rush growing up. By the time I was in high school, I had all but forgotten it. (Which is to say, when a friend first played me a tape of A Show of Hands, I knew I had heard of Rush, but didn’t remember having ever heard them.)

Metroid Games Ranked

I’m almost as much of a Metroid nerd as I am a Rush nerd. As with Rush, my first taste of Metroid was pretty far removed from my obsession with it. The same friend who introduced me to Rush in high school also owned an NES (I didn’t), and I played Metroid a few times at his house. I was intrigued by this disturbing and immense underground world, but it was also disorienting and brutally difficult.

For various reasons I never owned or even played an SNES (Super Metroid was released when I was a junior in college), and I totally skipped the N64/PlayStation generation of consoles too, because… my god, those polygons and textures just plain sucked, and the games all looked like absolute ass. The GameCube drew me back in though — the first actual console I owned since my Atari 2600 (not counting an Atari 7800 I bought NOS from Radio Shack’s mail order catalog in the late ’90s) — and I was obsessed with Metroid Prime, the first Metroid game I truly experienced.

A year or two later I bought a Game Boy Advance SP, and played Zero Mission and Fusion, then of course Metroid Prime 2: Echoes, also on the GameCube. I loved all of those. The DS Metroid games were kind of crap though, and I could never get the hang of the Wii motion controls on Metroid Prime 3: Corruption. Fortunately, the Wii also introduced the Virtual Console, and I finally got to experience the magic of Super Metroid. (That was also how I introduced my then 5-year-old son to the world of Metroid.)

After that, the Metroid franchise all but died out, because Nintendo seemed to actively try to kill it with misguided garbage like Other M and Federation Force.

And then came Samus Returns, on the 3DS. Ohhhhh man. That game scratched the itch. Needless to say, Metroid Dread carried on where that one left off, and I am eagerly awaiting Metroid Prime 4.

And now, the list:

  1. Metroid Dread (Switch)
  2. Super Metroid (SNES)
  3. Metroid Prime (GC)
  4. Metroid: Samus Returns (3DS)
  5. Metroid Prime 2: Echoes (GC)
  6. Metroid: Zero Mission (GBA)
  7. Metroid Fusion (GBA)
  8. Metroid Prime 3: Corruption (Wii)
  9. Metroid Prime Pinball (DS)
  10. Metroid II: Return of Samus (GB)
  11. Metroid Prime: Hunters (DS)
  12. Metroid: Other M (Wii)
  13. Classic NES Series: Metroid (GBA)
  14. Metroid (NES)
  15. Metroid Prime: Federation Force (3DS)

Finally… just in case you didn’t get the reference in this post’s title: