Refactoring Patterns in Block Themes

Written by Tinjure WP Posted on

Notes: This post is part 1 of leaning creating and block patterns using full site editing (FSE) interface in block themes. This learning post is still in active development and updated regularly.

In my previous learning-note post on creating block patterns, I have discussed in detail about how to register and create customized block patterns with a use case  example of customizing patterns from Quadrat theme for my own block theme project.

Now that block patterns can be directly loaded to block theme from /patterns folder without block registration just like /parts and /templates are automatically loaded to block theme.

Many theme authors, including the Automattic theme team, are creating block templates using patterns, however not entirely. For example these Automattic themes – Pendants, Archeo,  and others are good learning examples.

Learning Goals
Part 1: To create entire block theme templates based on block patterns only using experimental emptytheme (this post)
Part 2: Patternizing Block Templates

The objective of this learning-note post was to refactor the current /inc folder with /patterns and automatically load patterns from /patterns folder without registration, similar to /parts and /template-parts folders as per this Gutenberg GitHub ticket #36751.

For the testing purposes, I used experimental block theme resorted to emptytheme from this GitHub repository.

Loading Patterns Directly from Editor

This recent WP Tavern article and recently released Automattic’s Archeo and Brian Gardner‘s Frost experimental block theme.

<?php
/**
 * Title: A Pattern Title
 * Slug: namespace/slug
 * Description: A human-friendly description.
 * Viewport Width: 1024
 * Categories: comma, separated, values
 * Keywords: comma, separated, values
 * Block Types: comma, separated, values
 * Inserter: yes|no
 */
 ?>
 <!-- some-block-content /-->

For the purposes of this learning-note post, a footer-default.php patterns registered with PHP is refactored. An over view of registering and creating block patterns is described in this previous learning post.

Screenshot showing footer default in the inc/patterns folder.

Next we will move the above footer-default.php pattern file to /patterns folder and refactor so that it loads directly from the editor.

Step 1: Create /patterns folder at the root of the theme.

The first step is to create /patterns folder at emptytheme’s root and start creating patterns as PHP files.

Step 2: Add pattern data to the file header

Following this WP Tavern article I modified the patterns header data as shown below.

<?php
/**
 * Title: Footer Default
 * Slug: emptytheme/footer-default
 * Categories: emptytheme-footer
 * Viewport Width: 1280
 * Block Types: core/parts/footer
 * Inserter: yes
 */
 ?>
 <!-- some-block-content /-->
Step 3: Add Pattern Content to the file

For the content section, I copied code snippets within ‘ .. ‘ from the content section of footer-default and replace with the <!-- some-block-content /--> (line 11, step 3) with the following.

<!-- wp:group {"layout":{"inherit":true}} -->
<div class="wp-block-group">
	<!-- wp:group {"style":{"spacing":{"padding":{"top":"80px","bottom":"30px"}}}} -->
	<div class="wp-block-group" style="padding-top:80px;padding-bottom:30px">
		<!-- wp:paragraph {"align":"center"} -->
		<p class="has-text-align-center">Proudly Powered by <a href="https://wordpress.org" rel="nofollow">WordPress</a></p>
		<!-- /wp:paragraph -->
	</div>
	<!-- /wp:group -->
</div>
<!-- /wp:group -->

The screenshot below shows the entire code snippet of the patterns/footer-default.php file.

Screenshot showing modified footer-default.php file in /patterns folder.
Step 4: Refer patterns slug in the Template

The parts/footer.html template can be modified just to refer slug of the theme’s pattern file (footer-default) as shown below.

<!-- wp:pattern {"slug":"emptytheme/footer-default"} /-->

Now if we view our site’s footer part with block editor or front-end of our site in a browser, the footer section is displayed as before.

Note: Creating and displaying patterns without registration, as described above, greatly simplifies the process to create block patterns.

Pattern categories and types Registration

To categorize blocks patterns, the patterns categories and types should be registered in theme’s functions.php file. An example registering block patterns from the Archeo block theme is shown below.

// from Archeo functions.php file
/**
 * Registers block patterns and categories.
 * @since Archeo 1.0
 * @return void
 */
function archeo_register_block_pattern_categories() {
	$block_pattern_categories = array(
		'images'   => array( 'label' => __( 'Images', 'archeo' ) ),
		'featured' => array( 'label' => __( 'Featured', 'archeo' ) ),
		'footer'   => array( 'label' => __( 'Footers', 'archeo' ) ),
		'query'    => array( 'label' => __( 'Query', 'archeo' ) ),
	);

	/**
	 * Filters the theme block pattern categories.
	 */
	$block_pattern_categories = apply_filters( 'archeo_block_pattern_categories', $block_pattern_categories );

	foreach ( $block_pattern_categories as $name => $properties ) {
		if ( ! WP_Block_Pattern_Categories_Registry::get_instance()->is_registered( $name ) ) {
			register_block_pattern_category( $name, $properties );
		}
	}

}
add_action( 'init', 'archeo_register_block_pattern_categories', 9 );

The above registration displays theme specific patterns in the pattern inserter together with the core default patterns. To add theme specific categories label in the patterns inserter, we should modify the above snippets by adding theme namespace as follows.

// from emptytheme functions.php
/**
 * Registers block categories, and type.
 *
 * https://github.com/Automattic/themes/blob/trunk/archeo/functions.php
 */

function emptytheme_register_block_pattern_categories() {

	$block_pattern_categories = array(
		'emptytheme-header'   => array( 'label' => __( 'Emptytheme - Headers', 'emptytheme' ) ),
		'emptytheme-footer'   => array( 'label' => __( 'Emptytheme - Footers', 'emptytheme' ) ),
	);

	/**
	 * Filters the theme block pattern categories.
	 */
	$block_pattern_categories = apply_filters( 'emptytheme_block_pattern_categories', $block_pattern_categories );

	foreach ( $block_pattern_categories as $name => $properties ) {
		if ( ! WP_Block_Pattern_Categories_Registry::get_instance()->is_registered( $name ) ) {
			register_block_pattern_category( $name, $properties );
		}
	}
}
add_action( 'init', 'emptytheme_register_block_pattern_categories', 9 );

Now, if check our Emptytheme’s patterns from the block editor patterns inserter, theme specific categories are displayed as shown below.

 

Screenshot showing pattern category displayed in patterns inserter (left panel) and corresponding default footer pattern displayed in the editor (right panel).

The above described process greatly simplifies creating and displaying block patterns in block themes. This feature will be available with WordPress 6.0 without using Gutenberg plugin.

Wrapping Up

In this learning-note post, patterns files were moved entirely from /inc/patterns folder to theme’s root /patterns folder. The PHP registered patterns were refactored by modifying header section inside the /patterns folder.

NEXT: Patternizing Block Templates

Useful Resources

The following is list of references link that I gathered during my brief research. While preparing this post, I have also referred some of the following references extensively.