Tag Archives: Web Development

A Gutenberg/Block Editor revelation… just stop trying

This is not as defeatist as it seems by the title. I’ve actually had a huge breakthrough in my ongoing battle journey with the WordPress Block Editor (a.k.a. Gutenberg).

My biggest problem throughout the process of trying to build a Block Theme has been finding myself hamstrung by the lack of PHP in a Block Theme’s all-HTML template structure. I’ve ended up brute forcing my way into having access to PHP with a combination of ACF Blocks and Block Patterns. But it should have been obvious to me that both approaches were wrong, because I found myself creating ACF Blocks that didn’t have any custom fields and Block Patterns that didn’t have inserters.

The fact that I was using both of these tools in ways that they are patently not intended to be used should have been my first clue, but the problem has always been that documentation of all of this new technology is so scarce, inconsistent, poorly organized and out-of-date by the time it’s written, that it’s hard to really know in advance how they work, and whether or not you’re using them properly. And as my recent series of blog posts have indicated, I am the proud king of Doing It Wrong™.

But as I said at the beginning, I’ve had a revelation, which is this:

The only reason to create a pure “Block Theme” is if you intend to use the new Site Editor (a.k.a. Full Site Editing).

I emphatically do not intend, now or ever, to use the Site Editor, because I have always coded themes from scratch, and the people I am building sites for do not want to modify the overall design themselves, nor should they be given access to the tools to do so.

I am completely locking down access to the Site Editor on the sites I build, so why should I design my themes to work with it? Well… until now, I kind of just thought that was The Way Forward. Maybe it is, but it’s a way that does not, at all, align with how I do business or what my clients want/expect from me.

Luckily, core WordPress team member Carolina Nymark has written an excellent introduction to using PHP templates in block themes. It’s as simple as this. Just… use the old PHP-style of templates. There are a few tricks to be aware of, most of which are addressed by Carolina’s article, but some more I discovered along the way.

I’ve spent the last year and a half of building my block theme constantly butting up against this frustrating limitation. Now after about 4 hours of work, I’ve managed to convert my nascent Block Theme to using PHP templates.

I’ve eliminated my custom field-less ACF Blocks.

I’ve eliminated my un-insertable Block Patterns.

Things are working like they should. Well, mostly. This is an ongoing process. But the key test of the change has been that everything that was working in the theme before is working now, and I have the full capabilities of PHP and the long history of PHP-based WordPress development back at my disposal for future work.

I’ll write more about this in the coming weeks as I refine my process, including an overview of my general setup for a Block-friendly but PHP-rich base theme.

Update: Well, it seems rather fortuitous that I chose this undertaking when I did, because it coincides perfectly with the release of WordPress 6.2.1 which breaks shortcodes in Block Theme templates (which is even more of a shitshow for some people than it is for me, since it hadn’t occurred to me that shortcodes could be used as a workaround to the absense of PHP in Block Theme templates), including a pair of sites I’m currently developing using this theme. Switching those sites to the new PHP-based version of my theme should fix this issue automatically.

More Gutenberg madness (“This block has encountered an error and cannot be previewed”)

The WordPress Gutenberg project (a.k.a. the Block Editor) is supposed to make building WordPress sites faster and… well… once you get the hang of it, that often is the case. Recently I’ve actually marveled at how quickly it has allowed me to build out a site, now that my base theme is getting a bit more polished. And creating block patterns in WordPress 6 is super slick, after you learn a few of its quirks.

But then, the Block Editor will throw me a curveball that can derail things for days. For instance, there’s this:

I have a site using my custom theme that all of a sudden started throwing out this message after a recent update. It’s on the Separator block (a.k.a. a glorified <hr> tag). I took a look at the code, and there’s nothing overly complicated going on. The best clue I had to the problem was that it may have something to do with the .has-alpha-channel-opacity CSS class getting applied to the tag.

Then I noticed that in a child theme I’m building for another site, the error didn’t occur. I tried switching between the child theme and parent theme, and sure enough — with the parent theme, I get the error; with the child theme, I don’t. So… what is it?

Well… with almost any type of problem solving, it’s about trial and error, finding differences, ruling things out, and narrowing your search. But it was really hard to find anything between the parent theme and child theme that might cause this. Certainly there were no differences in how they treat Separator blocks.

I came back to that CSS class. Why is that there? Where Gutenberg is concerned, when in doubt, it’s always a good idea to have a look at the theme.json file. And, sure enough, that’s where the difference was. In my parent theme, I had this (note line 13):


But in the child theme, I had this:


Yes, for some reason, an empty array for the color.gradients setting allows the Block Editor to properly parse the Separator block, but a null value causes the error.

WHY???

I don’t know. I don’t really care. At least I was able to fix it. But this again makes me question the wisdom of the entire Gutenberg enterprise. I still don’t really buy the rationale that this JSON file is the way to go, although I am at least starting to understand why it was chosen. However I think this example illustrates some of the negatives of the approach.

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.

Not everything needs to be secure

Just saving this for future reference. I got on the “all HTTPS all the time” bandwagon without questioning it, because enough of the sites I create do collect user data that needs to be secure. But some — like this blog, for instance — do not.

But here’s an angle on it that I hadn’t considered:

If Google succeeds, it will make a lot of the web’s history inaccessible. People put stuff on the web precisely so it would be preserved over time. That’s why it’s important that no one has the power to change what the web is.

— Dave Winer

Google of course is always trying to change what the web is, just as Facebook does. I really got into a lather over AMP because it was immediately clear to me as a web developer how it is bad for the open web. Forcing everything to HTTPS is not quite as obviously “wrong,” but when you investigate it… yeah, it is.

This site uses HTTPS because… well, why not? I use Let’s Encrypt, so it’s free and easy. And I configured the server to automatically redirect HTTP traffic, so old links still work. But people shouldn’t be expected to understand what I understand about the web in order to use it… and not just as passive consumers, but as active contributors.

That’s the real power of the web, and what we lose when we let companies like Google or Facebook change the nature of what the web is.

I’d like to end with another quote from Winer:

The web is not safe. That is correct. We don’t want every place to be safe. So people can be wild and experiment and try out new ideas. It’s why the web has been the proving ground for so much incredible stuff over its history.

Lots of things aren’t safe. Crossing the street. Bike riding in Manhattan. Falling in love. We do them anyway. You can’t be safe all the time. Life itself isn’t safe.