Registering Block Patterns

The WordPress block editor provides opportunities for creating complex content for WordPress posts and pages. Content creators may find that configuring similar complex blocks again and again to be a cumbersome task. Fortunately, block patterns provide a way for easy access to pre-configured blocks and groups of blocks. Block Patterns are perfect for frequently used block configurations. This workshop will cover how to generate the markup for a block pattern in the block editor, and how to add the registration code for that pattern to a plugin or theme.

Learning outcomes

1. Configure blocks in the WordPress Block Editor
2. Know the difference between Blocks, Reusable Blocks, and Block Patterns
3. Register a block pattern category in a plugin or theme
4. Register a block pattern in a plugin or theme

Comprehension questions

• What is a block pattern?
• What is a block pattern category?
• Can you name 3-5 use cases for registering block patterns in your plugin or theme?
• How do block patterns differ from reusable blocks?
• What level of coding knowledge is needed to register a block pattern?

Transcript

Today I will share about Block Patterns in the WordPress Block Editor. You may already know that the Block Editor sometimes referred to as Gutenberg can be used to create really advanced and interesting content layouts. Today I will share about the Block Patterns feature that was added in WordPress version 5.5 in August of 2020. So what are Block Patterns and what makes them useful. The Block Patterns feature provides access to a catalogue of pre made patterns made of blocks that allow users to easily create and modify engaging layouts for their content. This feature is primarily available to allow theme and plugin developers to create predefined block configurations for their for their users and clients. Beyond those included in WordPress by default, additional Block Patterns can be registered to provide content creators with even more options for quickly creating highly customizable content or their website. Registered Block Patterns provide a very simple way to add template like groups of blocks to posts or pages ready for unique content to be added. From adding Block Patterns and unique to a site’s brand to extending a plug in or theme’s functionality, the possibilities are endless. More information about how to use Block Patterns can be learned in the intro to Block Patterns workshop.

I will take a moment to sidetrack to talk about another Block Editor feature that might cause a little confusion when talking about Block Patterns. This is the reusable block feature. A reusable block is a block or group of blocks that are saved to allow management from a central location. Changes made to a reusable block will apply to every instance of the block across an entire website. When a reusable block is edited, those files will affect any location on the site where the reusable block has been used. Block Patterns however, are used as a starting point and don’t have the same central management. Once a block pattern is added to a poster page, it is no longer connected with the registered block pattern and can be modified without affecting the block pattern that was used to insert the blocks. Now that we’ve learned what Block Patterns are, let’s take a look at the code used to register them. Block Patterns are registered for use from the block inserter panel by adding the necessary code to a WordPress theme’s functions.php file, or in a custom plugin. In order to keep the Block Patterns inserter organized the option to create block pattern categories can be registered along with the block block pattern itself. I recommend utilizing this option to keep things easy for content creators in the future. In this case, I have registered a block pattern category with a category name and a human readable label. The category name will be used by WordPress to identify the category. Note that I have used all lowercase characters separated by dashes for my category name. The second property contains an array with a label attribute. This assigns a human readable label for the category that will be listed in the category drop down menu in the Block Patterns inserter panel. The code to register the Block Patterns consists of two required and two optional properties, title and content are required properties. The description and categories are optional but recommended. The title will provide a label for your block pattern to be displayed in the list of available Block Patterns. The content contains the initial block content for the pattern. This content will also be used to create a rendering of the block as it will appear with the active theme styling in the inserter panel.

Depending on the content of your block pattern, it may be necessary to escape certain characters, such as double and single quote characters. There are many online tools available to help with this task. The URL for one option at onlinespringtools.com is shown here. Not here you see the completed code that can be added to a theme or plugin. In this case, I’ve added a simple paragraph block example for demonstration purposes. This code creates a function to register both the block pattern category and the block pattern and is added as an action on the WordPress init hook. I have also wrapped my registration code and an if statement so that the registration code will only be used if the Block Pattern functionality is present on the site where the code is added. This will act as a safeguard should the code be added to a site that does not support this relatively new feature of WordPress. Note that the strings I’ve included in my Block Pattern registration code are wrapped in localization functions to allow the strings to be translated into other languages. This is a best practice when coding any user facing strings. This example is extremely simple, but let’s look at the process for obtaining the content markup needed to register a somewhat more complex block based layout for registering a block pattern. The first step in preparing to register a block pattern is to create a post or page in a WordPress site. Using the Block Editor that will generate the markup to be included in the Block Pattern registration code, I will demonstrate this process now.

Here we have a basic WordPress site that was created for this demonstration. On the homepage, I have added each of the core or included in WordPress Block Patterns. And you’ll see we have things like a two button block pattern that includes two buttons just as it suggests that’s pretty button block pattern. And then if you go down the screen, you can see that we have a number of other options things like two columns of text with images, we have three columns with buttons, we have some that will do images. Here we have something that’s intended for a large header with a with a heading over the image. And as we continue down, you can see more. And finally we have a quote block pattern, which is a really good example of the type of thing you might use a block pattern for to create a way to have a very consistent layout with content that you might use again and again, up above what would be a really common thing where certain types of sites might use. So now I will create a new post, I’m going to go up here to you and then posts. So in order to get started, this post is really only included as a way to get the markup you will need in order to create your Block Patterns. So just to give the post a name. And I’ll say that this is a Block Pattern setup. And then I can start creating the block. And let’s say I wanted to know, let’s give it a heading, you can add another block here, perhaps for this, we would be maybe creating some kind of a team page. So we might wish to have an image, we might wish to have some kind of biographical content. So you could say that we’re going to have a name,we’re going to have a title, we could say we’re going to have some kind of biography.

We can apply some formatting to this content. So let’s say we want to make the name that will be replaced at a later time bolded. Or we can maybe say that we want to make the title. So we make the title, a small size. And then the biography which is regular content. Or we could say that we want to make this title have a smaller line height perhaps. So we can maybe say the line height is almost going to be one and then we can say that over here what we would have is a media where we have some kind of an image. And depending on a theme that you have installed, you may have styles that have been created specifically for your theme. You can set text and background colors and a number of other things that may depend somewhat on your theme or the blocks using your block category. One thing to watch for is to try to avoid having these extra paragraphs because when we go to create or get the content for this block pattern we will find that we need to remove those if they’re present. So just so that we have something in this media area, let’s go ahead and see what kind of images I’ve got in my Media Library. So just that we have an example, let’s say that in this case, we’re going to create a directory listing for a team mascot. Now we’ve added this image, I’m going to go ahead and try to make this a thumbnail. And let’s say I wanted to have the image on the right side. And I want to see what else we can do here, perhaps we want to make it smaller, so that it doesn’t take up so much space on the page. And we can see that this is just a very, very simple group of blocks, it’s not very complex. But you could add extremely complex full page layouts using this option. It could be used as starting points for things like landing pages, for example. So alright, so here I have my blog, I’m going to call this complete. And I am going to go ahead and save my draft so that I don’t lose my work. Now, the content here is not visible. So we can see the way that it’s designed to look. But we can’t see the markup that’s actually creating this. And so what we need to do is reveal that. And to do that, we’re going to go up here to the options, which is the three little dots in the upper right hand corner of your screen. And then we’re going to change from the visual editor to the code editor. And this will change the screen, we will still see our top, our title here Block Patterns setup. This can be edited, I would not recommend editing your content in this view unless you’re very familiar with HTML and block markup. Because it would be quite easy to break your content. WordPress is very specific about the format that it needs some information to be in. So if we look at what the makeup of this book, what will become our Block Patterns, you can see we start with this commented out HTML that says, WP colon heading. This will not be displayed for end users. But WordPress will see it, it will be in the markup of the front facing content. But it’s only intention is to let WordPress know that this is actually a heading block. So we open that with a commented out block of HTML, and we close it with a commented out block of HTML. And in between those two comments is the actual content of that block. So a slightly more complex example is the media dash text for our media content block. And in this case, we have blocks inside of blocks. So we open the block. So let me go ahead and select this. So you can see all the opening content.

There’s a number of actions, attributes, and properties set here. So actually, the true opening is this much. So it tells WordPress something about this, how it’s going to work with this content is up to WordPress. And in this case, we are only using core blocks and the plugin blocks. But in some cases, you might have additional blocks that are added by your plugin or in some cases, blocks could be registered and things as well. So after this, we have the content of the block. And then inside of this block, we have a second paragraph block and actually two paragraph blocks and then a third. And then once all of those inner blocks are done, then the outer block’s HTML is closed, and then the outer block’s comment is present. So what we have our nested blocks in this case, so as you can see, it’s possible to have very customizable and advanced block layouts here. And this is one of the reasons why a Block Pattern can be so useful if you have very complex content that you’re going to use again and again. So in order to create the registration code, all we’re going to do is take this code, and we’re going to put it into the content section of the registration code that I showed you before. And let me go ahead and I will go into my plugin. This is not something that I would recommend doing. But just as a simplified way of getting to the code, we’re going to go into the plugin editor. On many hosts, I’ve actually disabled this. So this is my simple Block Patterns plugin. And here I’ve registered some Block Patterns. I have one example here that I did previously, that’s called my pet details. And if I scroll down, then I have a second Block Pattern that I’ve registered, that has a more simplified version. And what I can do is just take that code that I copied out of the post and paste it in here. So that is basically what you can do here to register your Block Pattern. One note to be aware of is that especially if you have things like apostrophes, or, quotation marks, either single or double quotation marks and your content or any other character that would need to be escaped for PHP to not change the way that understands the code you’ve added, anything that’s in between the single quotation marks around your content property of your registered Block Pattern, you would want to escape this content. And there are a lot of different options for escaping content, the one that I’ve used is onlinescreentools.com/escape-spring. And if you just search online for a string escaper, you would be able to find a tool that you could copy your markup into it, and then it would give you the escaped string, I will tell you that if you do that, you’ll want to remove all of your line breaks and extra spacing here so that what you get out is a very clean version of your HTML markup. So that when you paste it in here, you won’t have any extra linebreak characters or empty spaces or those kinds of items. So in this case, actually, I can look through the code, and I can see that I won’t have any characters that will interfere with the rendering of this block, I do have some double quotation marks in the markup. But because I’m wrapping this in single quotes, it won’t cause a problem. So it all depends on what kind of content you have, apostrophes or a contraction in your content with potentially a problem. So once you have added this block pattern, you can then go back to a post.

And let me demonstrate the way that you would add a Block Pattern. First of all, we’re going to change back to the visual editor. So that’s the options, three dots in the upper right hand corner. Switch back to Visual Editor, you can see now we have our regular WordPress Block Editor view. In order to add a block pattern to some content, you would open up this primary inserter. This is where all blocks available will be available to you. And you will see that there are patterns. And in some cases if you have saved previously reusable blocks that can be accessed from here. So patterns can be accessed by clicking on the patterns tab. There’s a drop down that will show you the categories. And all of your Block Patterns that are registered for your site will be available here. So let me just check here I believe that I may have actually deactivated my Block Patterns plugin. So let me go ahead and get that activated. And then let’s try this again to see the Block Patterns that I created. So now you can see here now that with that plugin activated I can see the category of my custom patterns. And when I open that up, I can see two Block Patterns. So these are two that I created previously. One of them has quite a lot in it. The other one is more simple. If I just click on it, then I add it in to the end of the document that I have open. And then what I can do from here is go ahead and start editing it. Once I’ve inserted this Block Pattern into my post or page it’s no longer connected with that block pattern. A block pattern is there again to use again in the future, but I can go ahead and make any changes I need to this group of blocks. This concludes this workshop. I hope you find new and interesting ways to use the Block Pattern feature of the WordPress Block Editor in your work. Thank you.