Should we use WooCommerce Block Theme Syntax in 2022?

Short answer: no, we shouldn't (yet)!

There are many reasons not to use WordPress as a developer, and since 2022, there is one more: full-site editing (FSE) using the block editor also known as Gutenberg.

WordPress Full-Site Editing from a Web Developer's perspective

In this post, I will share some coding horror and try to offer pragmatic solutions based on my own experience as one of those web developers still occasionally helping customers to use and customize their WordPress sites.

As a general tip concerning any recent or brand-new WordPress feature: don't be an early adopter, unless you have a good reason to do so! Last year, I found out that I probably upgraded WordPress to PHP 8 too early and this time, I used WooCommerce's new block syntax before it fully supports other plugins like Pods or Germanized.

WordPress Syntax Horror and Inline Styles

While full-site editing might be a great progress from an editor's point of view, what does it mean from a developer's perspective?

Writing a block theme in 2022 means using a new technology that is partially still a work in progress, using syntax produced by a ReactJS-based WYSIWYG-editor that produces code like this:

<!-- wp:heading {"textAlign":"center","className":"has-text-special","fontSize":"gigantic-responsive"} -->
        <h2 class="has-text-align-center has-text-special has-gigantic-responsive-font-size">
          Lorem Ipsum
        </h2>
        <!-- /wp:heading -->

Custom Blocks and Template Parts

We can use this syntax to define and include custom blocks and template parts in our theme.

<!-- wp:template-part {"slug":"breadcrumb-default","theme":"my_block_theme"} /-->

which will include a file block-template-parts/breadcrumb-default.html...

<!-- wp:pattern {"slug":"foodtogether/breadcrumb-default"} /-->

which just calls another file, block-patterns/breadcrumb-default.php where we can use PHP functions like get_template_directory() just like we would in classic WordPress themes, and we can use block editor syntax in the returned content.

<?php
/**
 * An example breadcrumb
 *
 * @package MyBlockTheme
 */

return array(
    'title'      => __( 'Custom Block', 'my_block_theme' ),
    'categories' => array( 'breadcrumbs' ),
    'content'    => '<!-- wp:group -->
<div class="wp-block-group has-grey-200-background-color">
    <!-- wp:group -->
    <div class="wp-block-group">
        <!-- wp:yoast-seo/breadcrumbs /-->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->'
);

Mixing and Messing up Style and Content

As users / editors will use our theme, they will have to edit some of the content, like H1 heading text, using the full-site editor, thus modifying parts of our theme. Now they can either keep editing or revert their changes to the original theme files.

This should at least be restricted to page templates, so at least our template parts / blocks remain untouched, but still we have to check if the changes introduced new inline styles and if our markup structure and custom class names are still like we expected them to be!

WP Presets in theme.json

WordPress block themes provide a bunch of CSS custom properties, like --wp--preset--color--grey-100 which are set in a file called theme.json.

Although this is more orderly than arbitrary custom CSS blocks or even more inline styles, it makes searching and modifying styles in our IDE a bit more complex.

We might see something like this CSS

color: var(--wp--preset--color--grey-100);

or this class name

<div class="wp-block has-grey-100-background-color"

both of which refer to a custom property --wp--preset--color--grey-100.

At least in late 2022, I don't know any extension to make my IDE understand where this custom property is defined, so there is no hint nor preview in my editor, and I will have to use my brain and/or search engine to learn that this is a block theme preset defined in theme.json here:

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "grey-100",
                    "color": "#EEEEEE",
                    "name": "Grey 100"
                },

Developing Customized WordPress Themes

What does this mean for development? If we have a local WordPress instance (preferably based on the official WordPress docker image), we will have to synchronize the changes back to our local environment and repository. We can use a content export, store the resulting content.xml in our repository, and then put the changes back into our files.

On the other hand, if we want to change markup, we will have to edit in two places, both in our code and in WP-Admin. The block editor has a code view at least.

Documentation of the new WordPress features is mostly written from an editor's / publisher's point of view, and I did not find an official block editor code syntax documentation yet, so expect a lot of trial and error when working with the block editor as a developer.

See the conclusion section below for some helpful links.

Even more Complexity thanks to Plugins

WordPress is infamous for the millions of available third-party plugins, most of which have not been adapted to fully support full-site editing.

But we can use shortcodes, the good old bracket syntax like [products] or [pods].

Now imagine a block theme working together with traditional plugins like WooCommerce or Pods. We will have HTML, CSS, JavaScript, PHP, WordPress shortcodes, and WordPress full-site editing / Gutenberg block editor syntax which is basically JSON syntax inside HTML comments.

PHP vs. JavaScript

Some plugins, like WooCommerce, offer alternative ways to do the same thing. We can use a traditional [products] shortcode (with optional parameters) or the new <!-- wp:woocommerce/all-products --> block. While the shortcode variation will trigger PHP code in the backend before the page is rendered and sent to the client, the block variation will use client-side JavaScript making additional WordPress API calls to display same content that is similar at least visually.

Both variations will produce different markup, using different CSS class names, and even a different markup structure with more or less wrapper elements. So we can't write concise CSS that will work with both variations. And talking about CSS, we have to use !important frequently to fight all the inline styles added by the new block editor.

PHP Hooks are not called by JavaScript Blocks!

Any third-party plugin that relies on hooks provided by the traditional PHP code, will not work when using the new JavaScript-based block variation!

Two particular examples that I recently found:

• Germanized, a plugin that extends the WooCommerce e-commerce plugin adding unit price display and other details necessary to comply to German trade laws, does not fully support WooCommerce blocks yet! See this (German) support issue about missing unit prices when using the all-products block: Germanized for WooCommerce » Grundpreis fehlt auf Produktarchivseite
• Pods, a popular extension to add custom post types, fields, taxonomies, and relations to WordPress data, offer many shortcodes and "magic tags" (shorthands for loops) some of which do not work inside WordPress block syntax.

Conclusion

Either we, as developers, have to provide an open-source replacement that is as easy to use from a customer's / editor's point of view, or we have to find a way to use WordPress in a more maintainable way.

If you plan to use full-site editing now, be prepared to discover compatibility problems, and have a look at the WordPress core development roadmap, newsletters, and community events.

Dont't give up shortcode and PHP code (yet)! Apart from compatibility issues, some things are best done on the server side. See the server-side rendering (SSR) discussions in the ReactJS and VueJS community, e.g. Server-Side Rendering (SSR) Vs Client-Side Rendering (CSR). Generating our markup on the server side can benefit web performance due to better caching , using client-side caching, content delivery networks (CDN), WordPress plugins like W3 Total Cache (W3TC) or all of the above and can also help search engine optimization (SEO).

Although full-site editing (FSE) and block-editor (Gutenberg) documentation is mostly written for webmasters, it can still help to read it as a developer so that we can understand the concepts behind the new technology. Some useful resources:

• FullSiteEditing.com by Carolina Nymark
• Gutenberg-Fibel (in German) by Jessica Lyschik