Full Site Editing
With WordPress

In this article, I explore how to add templates for WooCommerce in full site editing themes.
I wanted to learn if it is possible to customize shop pages and checkouts and if we can edit our products visually with drag and drop, adding our brand colors by only using block settings.

I learned that we are almost there; creating a fully working shop is possible, but you can’t customize every detail via the WordPress block editor.

At the end of the lesson, I share the code for my example WooComerece templates. Go ahead and jump right to the code if you prefer!

Estimated reading time: 17 minutes

Updated April 5, 2022. Details and screenshots are of WooCommerce version 6.3.1.

Is WooCommerce compatible with full site editing?

WooCommerce has partial support for full site editing.
Not all WooCommerce template functions and actions have a block or block setting equivalent, meaning that customizing block templates is limited compared to classic templates.

One big drawback, as you may already know, is that WooCommerce still uses the classic editor for creating and editing products in the WooCommerce admin interface.
Another missing part is blocks for the account page, including editing account information and viewing orders.

There are essentially four ways to add support for WooCommerce in a full site editing theme:

• The classic template block
• Product blocks
• WooCommerce Shortcodes
• Free and paid third-party block plugins

In this article, I will compare the first two options, but I will not go into using classic WooCommerce shortcodes with the shortcode block.
WooCommerce recommends using the blocks instead of the shortcodes.

Templating for WooCommerce

Creating WooCommerce templates for a full site editing theme is similar to adding support for WooCommerce in a classic theme.

• Templates follow the template hierarchy (Where product is a custom post type) but you can customize which template to use in the plugin settings.
• If a theme does not include templates, WooCommerce will display its default templates.
• Block themes uses .HTML instead of .PHP files and blocks instead of functions.
• Templates are placed in the templates folder instead of in a woocommerce folder.
  

archive-product.html	Product archive/shop page. If you have set up WooCommerce with default settings, this is the page that WordPress shows at example.com/shop/.
single-product.html	Single product view.
page-checkout.html	Checkout (use with the WooCommerce Blocks plugin).
page-cart.html	Cart (use with the WooCommerce Blocks plugin).
page-shop.html	Alternative shop page.
taxonomy-product_tag.html	Product tag archive.
taxonomy-product_cat.html	Product category archive.

Using the WooCommerce classic template block

The classic template block does what the name indicates: it includes a full template with the classic product views. It adds complete shop and product pages fully functional on the front but not editable in the Site Editor.
There is no way to preview or customize elements using the Site Editor. The entire template is one single block:

The classic template block (alias Legacy Template) is the block that WooCommerce uses in its default templates. A benefit of adding the block to the theme instead of relying on the fallback is that you can combine the product views with other default blocks on the same template.

You will not find the classic template block in the block inserter. Instead, you need to add the block markup manually.
The prefix and slug for the block is wp:woocommerce/legacy-template, and the template attribute tells WordPress which template to use. Examples:

• archive-product.html for the product archive and shop page
  <!-- wp:woocommerce/legacy-template {"template":"archive-product"} /-->
• single-product.html single product view
  <!-- wp:woocommerce/legacy-template {"template":"single-product"} /-->
• taxonomy-product_tag.html product tag archive
  <!-- wp:woocommerce/legacy-template {"template":"taxonomy-product_tag"} /-->
• taxonomy-product_cat.html product category archive
  <!-- wp:woocommerce/legacy-template {"template":"taxonomy-product_cat"} /-->

If you place the block inside a group block with the option “Inherit default layout” enabled, the block also supports wide and full width attributes:

<!-- wp:woocommerce/legacy-template {"template":"archive-product","align":"wide"} /-->

Important: This block uses a wrapper with a <main> element. Make sure that your page only contains one <main> element. Read “Use Only One <main> on a Page” by Adrian Roselli.

Styling the classic template

To style details like text colors and buttons in the classic template block, you need to use CSS and not theme.json. Elements in this block use the old classic CSS classes which are not prefixed, such as price, onsale, and add_to_cart_button.
You can add a new separate stylesheet that you load conditionally (recommended) or add your WooCommerce CSS to your existing stylesheets.

Using WooCommerce Customizer settings

WooCommerce includes a small set of Customizer options that can only be used with the classic template block. You can change the product image sizes and adjust the number of columns and rows on the product and category archives.

You do not need to make any changes to the theme to activate the Customizer, it is re-enabled by default. To learn more, please see the lesson How to re-enable the Customizer in block themes.

Using WooCommerce filters and hooks

While editing is not possible through the Site Editor, you can still use WooCommerce filters and hooks in your full site editing theme.
Note that some of the filters only work for the classic template block.
I recommend the Action and Filter Hook Reference in the WooCommerce Code Reference and the theming snippets (code examples).

Using the WooCommerce product blocks

Blocks for WooCommerce are not a new feature, but with the help of full site editing, both developers and site creators can place and preview the blocks anywhere on the site and in the content. You can showcase featured products, use a product in a call to action, display selected reviews and products from specific categories, or add a product search.

As a theme developer or designer, you can create custom styles for the blocks and combine them into block patterns, helping users highlight their most important products.

Less than ten themes in the WordPres.org theme directory include patterns for WooCommerce blocks, so there is a big opportunity to create something unique and useful (March 2022).

Compared to the classic template block, you can preview product blocks in the block editor and Site Editor and combine them to create new page sections.
Some of the blocks use WordPress core blocks as inner blocks, and many settings will feel familiar. For example, the featured product block has settings that are similar to the cover block and uses a product image and a button block:

List of available blocks

WooCommerce version 6.3 includes the following blocks:

• All products
• All reviews -Show a list of all product reviews.
• Featured category -Visually highlight a product category and encourage prompt action.
• Featured product -Visually highlight a product or variation and encourage prompt action
• Hand-picked products -Display a selection of hand-picked products in a grid.
• Best selling products -Display a grid of your all-time best selling products.
• Product categories list -Show all product categories as a list or dropdown.
• Products by category -Display a grid of products from your selected categories.
• Newest products -Display a grid of your newest products.
• On sale products -Display a grid of products currently on sale.
• Products by attribute -Display a grid of products with selected attributes.
• Top rated products -Display a grid of your top rated products.
• Reviews by product -Show reviews of your products to build trust.
• Reviews by category -Show product reviews from specific categories.
• Product search -A search box to allow customers to search for products by keyword.
• Products by tag -Display a grid of products with selected tags.
• Filter products by price -Allow customers to filter the products by choosing a lower or upper price limit. Works in combination with the All Products block.
• Filter products by attribute -Allow customers to filter the grid by product attribute, such as color. Works in combination with the All Products block.
• Filter products by stock -Allow customers to filter the grid by products stock status. Works in combination with the All Products block.
• Active product filters -Show the currently active product filters. Works in combination with the All Products and filters blocks.

A closer look at the All Products block

If you compare a shop page created with the classic template block and one made with the all products block, you can see some differences in styling, mainly on the sales badge, the order list, and the product title:

The differences are more significant in the editor. The classic template has no block settings besides the width, and only very limited Customizer settings.
The all products block has block settings for the number of columns and rows, aligning the last block, showing or hiding the sorting dropdown, and the product order.
You can use the default order, show the latest products, or sort products by popularity, rating or price.

The block also has an advanced hidden editing feature that you access via the pen icon in the block toolbar:

This editing mode unlocks moving, removing, and customizing inner blocks and is a delight to work with. It is easy to select the inner blocks and reset the blocks to the default:

List of inner product blocks

• Image
• Title
• Price
• Rating
• Add to cart button

These inner blocks are not available as stand-alone blocks in the block inserter.
The product image and add to cart button can be added to templates using block markup and a product ID.

Product image

The product image block has settings for linking the image to the product page, cropped or full size image, border radius, and margin.
In addition, it has settings for managing the on-sale badge: Show or hide, align to left, right or center, and font size.

Product title

Toolbar: Select between heading level H1-H6, left, center, or right alignment.
Block settings sidebar: Linking to the product page, margin, text and background color, font family, font size, font weight, line height, and letter casing.

Product price

Toolbar: Select between left, center, or right alignment.
Block settings sidebar: Text color, font size, and font appearance (bold, italic).

Product rating

Block settings sidebar: Text color, font size, and margin.

Add to cart button

Block settings sidebar: Text and background color, padding, font size, font weight, and border radius.

Styling WooCommerce product blocks

The product blocks use CSS classes prefixed with wc-, but they also use WordPress core blocks. In the example of the featured product, the button is an actual button block, and it inherits the styles you have added to the button block.

The new components and naming convention for the CSS classes makes it easier to style the shop elements. To style product images, you can use .wc-block-components-product-image img. The price component is styled with .wc-block-components-product-price.
And to style the button block inside the featured product separately, you would need to target
.wc-block-featured-product .wp-block-button__link.
If you want to style the product title inside the featured product block, use .wc-block-featured-product .wc-block-featured-product__title.

These are only examples. To locate the correct classes to use, please see the source code of the respective block.

Experimental WooCommerce blocks

The WooCommerce Blocks plugin is where the WooCommerce developers create and test new block features. It does what Gutenberg does for WordPress, but for WooCommerce. Version 6.4 of WooCommerce, with a planned release in April 2022, will include the blocks from WooCommerce Blocks version 7.2.

The checkout, mini cart, and cart blocks are three blocks essential for supporting WooCommerce in full site editing themes. For now, these blocks require the WooCommerce Blocks plugin to be active on your website. Despite the blocks being in development for two years, they are still experimental. Many parts, especially the design, still feel unpolished: But it’s nothing that you can’t fix with a little bit of extra CSS.

Note: When you create full site editing templates for these blocks, you can preview the block in the template in the Site Editor. But if you navigate to example.com/cart and select “Edit page,” the page will show the shortcode, not the block. Unless you have already created it yourself, the page is created automatically by WooCommerce.

Cart block

The cart block has two inner blocks, the filled cart and the empty cart, which in turn have other blocks nested inside them: Switching between the two carts requires selecting the inner block in the list view:

Limiting this selection to the list view can be a double-edged sword: it reduces the clutter in the editor but only works if the user knows how to use the list view.

By default, the inner blocks of the filled cart are locked, and you can not move or remove blocks; this is great because it prevents us from accidentally breaking our carts!
With Gutenberg 12.9 or newer, administrators can unlock the blocks by selecting the lock icon in the block toolbar:

The filled cart shows products and cart totals in two columns. With the blocks unlocked, you can reposition the columns and the items inside the cart totals.
But there is no way to order the products or show the products and cart totals in one column instead of two.

There are also no settings for text sizes, colors, or adjusting button text. You can add a few new inner blocks: images, paragraphs, and separators.

The empty cart comes with prefilled default blocks and is fully editable. The default blocks are two headings, a paragraph linked to the store, and the three latest products.

Mini Cart block

The MiniCart is a unique block because it has a custom template part for the cart drawer. This template part is not listed in the Site Editor’s template part list, but you can access it from the block settings sidebar.

Like the cart block, the mini cart has a filled and empty cart. The filled cart is locked, and the empty cart is fully editable.
The template part does have some color issues when added to dark themes:

Checkout block

The checkout block is another complex block with several inner blocks. The checkout fields (displayed on the left) and the checkout totals (in the right column) are the two main blocks.
The inner blocks are locked by default. They include contact information, shipping address, shipping options, billing address, and payment options.

This block feels more developed than the two cart blocks, and there are several helpful block settings. You can switch the position of the checkout fields and the order summary, edit the address fields, show or hide the step number, or let users sign up for an account.
There are also direct links from the block sidebar to the different plugin settings for easier management.

Conclusion

After comparing the classic templates and the available blocks, I opted to use the product blocks to create the shop page, cart, and checkout. The product block settings creates a much more pleasant and effective editing experience compared to using the classic template.

For the single product page, I would have liked and expected to be able to use blocks like a product title, a stand-alone product image or gallery, and a long and short product description. But these blocks are not available unless you use a third-party plugin.
For this reason, I choose to use the classic template for the single product page.
The website would also fall back to using the WooCommerce defaults for the account pages.

A caveat is that when you use two different types of WooCommerce block templates in your full site editing theme, you also need to target both the classic CSS classes and the new prefixed classes in your CSS.
– I can also imagine that it will be confusing for users that there are Customizer settings, but they only work for some pages.

Template examples

I first added the themes default header and footer template parts and a group block wrapper in each template I created.

Shop page and product archive

For the shop page, product-archive.html I added a columns block with the “filter by attribute” block in the narrow column and the “all products” block in the main column.
Finally, I placed a spacer and a product search block below the products.

Cart

For the cart, page-cart.html, I used the cart block from WooCommerce Blocks with default settings. I made the cart wide, and I removed the image of the sad smiley from the empty cart block variation.

Checkout

The checkout page is named page-checkout.html. As with the cart block, I changed the width from the default to wide.

Single product page

The single product page, single-product.html only uses one additional block:

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"align":"full","layout":{"inherit":true}} -->
<div class="wp-block-group alignfull">

	<!-- wp:woocommerce/legacy-template {"template":"single-product"} /-->

</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Resources

I am not a WooCommerce expert, and initially, I had some trouble finding the documentation that I needed and ran into broken links and whatnot. I want to share these resources with you so that you can continue to learn from them.

Follow the WooCommerce Blocks GitHub repository to keep track of changes and known limitations and bugs. (For those curious about how the blocks are built, here is a direct link to the source of the classic template block).

The WooCommerce Blocks Handbook in the same repository includes information about the new Store Rest API, actions and filters, the classic template blocks, and useful tips on how to override the default CSS.

Follow the WooCommerce developer blog for news and tutorials.

The WooCommerce documentation describes how to replace the cart shortcode with the new cart block.

As with many other plugins, not all WooCommerce extensions support full site editing yet.
See the list of extensions compatible with the new cart and checkout blocks.

WooCommerce has not updated its theme developer handbook to include information about full site editing. Visit this link for a refresher about integrating WooCommerce with your theme.