Some perspective on Gutenberg

Today I had to do some work on a client’s site that I didn’t build but have ended up maintaining, which is built from an amalgam of multiple “page builder” plugins, but most prominently, WP Bakery.

I was just explaining to my wife (who is not a developer but who uses WordPress, both Classic Editor and Gutenberg/Block Editor, extensively) what it’s like to use WP Bakery:

“Imagine the most annoying aspects of Gutenberg that you find the most annoying*, then imagine something ten times clunkier, a hundred times uglier, and a thousand times less intuitive. That’s WP Bakery.”

—Me

*Yes I really did, deliberately, say it that redundantly.

Vindication!

I already mentioned this in an addendum to my last blog post, but it seems to warrant its own dedicated post.

I’m a self-employed, solo developer, not very actively engaged in the WordPress “community” even though my work is 95% WordPress. So I have apparently missed the memo that shortcodes were (prior to yesterday’s release of WordPress 6.2.1, anyway) the way people were injecting PHP into their HTML-based Block Theme templates. (Silly me… I was just misusing Block Patterns to the same effect.)

Well… as it turns out, allowing shortcodes in Block Theme templates apparently was a security issue, which the WordPress core team summarily “fixed” by just outright removing shortcode support in templates in this update.

This change did break a pair of sites for me (which are still just in final testing, not live, and which I need to go fix as soon as I finish writing this), but the problem was relatively minor. It sounds like a lot of people are using shortcodes extensively as a backdoor hack for adding PHP functionality to templates, and they are… um… not happy.

At what point does the Gutenberg team collectively take a step back and realize that maybe they’ve been the ones Doing It Wrong™ all this time? I feel like that reckoning is approaching.

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 Doing It Wrong™: making Navigation blocks editable… sort of

By this point I have more-or-less embraced Gutenberg, a.k.a. the WordPress Block Editor. But I have not embraced Full Site Editing, a.k.a. the Site Editor, and I am not sure I ever will. I do not know who it is for, although I suspect it is for people who do not yet exist… namely, future WordPress freelancers who don’t know how to write code. The types of power users/professionals who currently spend their time in the ecosystems of tools like Divi, Elementor, Beaver Builder, etc.

Anyway… the present-day moving target of using the Block Editor as a professional site building interface has some weird gaps in its capabilities. And site navigation, in particular, is a chasm, a crevasse, a gaping maw of unfinished business.

Navigation has never been a particularly strong suit of WordPress, since WordPress was envisioned as a blogging tool and not a general-purpose CMS. Going back to the early days of constructing navigation piecemeal by setting a parent page and menu order on each individual page, to plugins like CMS Tree Page View, to the well-designed but weirdly detached custom menus that have been a staple of WordPress development lo these many years, building menus in WordPress has always been a bit “off.” I get what the core team is going for with the new Navigation blocks, but they’re still not quite flexible enough for code-centric developers like myself, and more importantly, there’s no way to just edit them directly.

The Block Editor has introduced a couple of types of “reusable” content that gets stored as standalone entries in the wp_posts table. First you have Reusable Blocks which are awesome. And then you have Navigation Blocks, i.e. the purpose of this post.

Something that’s a bit sticky about both of these types of reusable content is that there isn’t really a standalone way to edit them. And it doesn’t always make sense — despite what the core team apparently thinks — to always edit them in context (either the Site Editor or the Block Editor within a page). Because sometimes a theme developer might want to put them right into a template. (And a theme developer might not want to use the Site Editor to build their templates, which I believe will always be a legitimate approach.)

So, what do we do? Well, Bill Erickson has a great post showing how to add Reusable Blocks to the admin menu. This works incredibly well, and I’ve built it into my new base block theme. What I really like about it is that it works just the way you would expect — you get the Block Editor, but the only thing in it is the reusable content itself.

Building off of this, I thought I might be able to take the same approach, just using the wp_navigation post type instead of wp_block. And it works, at least, to the extent of getting a Navigation Blocks item to appear in the admin menu, taking you to an index page that lists all of the stored Navigation blocks, and an editing screen for those blocks.

But it’s a classic editor screen. Without the editor. You can change the title of the Navigation block, but if you want to actually edit its contents, you’re out of luck.

Digging around in the WordPress source code reveals some clunky code (includes/admin-filters.php, lines 87-89) designed specifically for the purpose of preventing direct editing of the Navigation blocks:

add_action( 'use_block_editor_for_post_type', '_disable_block_editor_for_navigation_post_type', 10, 2 );
add_action( 'edit_form_after_title', '_disable_content_editor_for_navigation_post_type' );
add_action( 'edit_form_after_editor', '_enable_content_editor_for_navigation_post_type' );

(This bit of code also reveals that even the core team has trouble telling the difference between actions and filters.)

I haven’t figured out why the core team doesn’t want us to do something it seems obvious that we’d want to do but… well, when have I ever let that stop me?

I’m still trying to figure out how to actually get the Block Editor to load. Removing the use_block_editor_for_post_type (ahem) “action” doesn’t do it, and neither does adding my own (ahem) filter that does the opposite. So, for now, we are left with the classic editor. But I did figure out a way to get it to always default to the Text tab, since the Visual tab won’t display anything. (I haven’t bothered to put in the effort to figure out how to only display the Text tab, but anyone who wades this deep ought to know what they’re getting themselves into.)

Here, then, is my variation on Bill Erickson’s Reusable Blocks code. This will get the Navigation Blocks item to appear in your admin menu:

function rm34_admin_menu_navigation() {
    add_menu_page(
        'Navigation Blocks',
        'Navigation Blocks',
        'edit_others_posts',
        'edit.php?post_type=wp_navigation',
        '',
        'dashicons-welcome-widgets-menus',
        34
    );
}
add_action('admin_menu', 'rm34_admin_menu_navigation');

And once you have that going, then you can use this to get the editor to appear, and to default to the Text tab:

function rm34_enable_wp_navigation_editor() {
    add_post_type_support('wp_navigation', 'editor');
}
add_action('edit_form_after_title', 'rm34_enable_wp_navigation_editor', 11);

function rm34_enable_wp_navigation_editor_text_mode($r) {
    global $post;
    if (get_post_type($post) == 'wp_navigation') { $r = 'html'; }
    return $r;
}
add_filter('wp_default_editor', 'rm34_enable_wp_navigation_editor_text_mode');

(Note: You could use the private _enable_content_editor_for_navigation_post_type() function instead of the add_post_type_support() line, since it does the same thing, but I’m avoiding using private functions. Even I am not that much of an iconoclast. What I’m doing here, specifically with the 11 priority, is turning the editor back on for wp_navigation posts immediately after it has been turned off, rather than on a later action as the above code excerpt from includes/admin-filters.php does.)

What you choose to do from here… well, I don’t really want to know. You need to be able to edit raw Gutenberg comment tags, because that’s what you’ll be working with. And just be aware that the code does not include the <!-- wp:navigation --> tags that wrap everything when the block actually gets used in a page.

In my case, I just wanted to get the data to paste directly into my template, so I wasn’t just stuck with a ref number for a menu I had no direct way to modify. Once I got the code, I deleted the saved Navigation block altogether.

All of which is to say, the old nav menus made a lot more sense from a coding perspective.