Category: Beginners

Categories
Beginners Tutorials

What is a custom block pattern?

A block pattern is a group of blocks, or a block with a predefined content and style.

If you would prefer to watch a video on this topic, I have recorded one for you here. A transcript is also available.

The purpose of a block pattern is to make it easier and faster to add common design elements and sections to a page or post.

Block patterns were added to WordPress in version 5.5.

If you have not updated WordPress yet, you can still use block patterns with the Gutenberg Plugin installed and activated.

In an earlier plugin version, patterns had their own sidebar panel, but they are now found in the Add Block menu in the upper left corner of the editor:

Block patterns can be found in the search or it its own tab in add block menu.

There are also a few example patterns available in version 5.5, that you can check out, like the two buttons above.

How to register a block pattern

To register a block pattern, themes and plugins can use the new PHP function called register_block_pattern.

Note that this function was renamed from register_pattern to register_block_pattern in Gutenberg version 8.1.

You can read the official documentation for the function here:

https://developer.wordpress.org/block-editor/developers/block-api/block-patterns/

register_block_pattern accepts a name (prefix), a label, and an array with two required parameters: Title and content.

  • Title is the name of the pattern that will be visible in the pattern selection panel.
  • Content is the HTML source code of your block pattern.

There are four optional settings:

  • Description -A visually hidden description that can describe the pattern to screen reader users.
  • ViewportWidth -Sets the width of the pattern preview in the editor, for example if your pattern is very narrow, like a sidebar (int).
  • Keywords -An array of words that can help users find your pattern in the block editor search. -Remember to make these words translatable for international sites.
  • Categories -Block patterns are sorted under categories in the “add block” menu. Categories are optional. You can choose one or more of the following categories:
    • Buttons
    • Columns
    • Gallery
    • Header
    • Text

Or, you can create your very own custom block pattern category using the PHP function register_block_pattern_category.

Example:

register_block_pattern_category(
     'quotes', 
     array( 'label' => __( 'Quotes', 'textdomain' ) )
);

register_block_pattern(
    'theme-prefix/block-pattern-label',
    array(
        'title'      => __( 'Hello Quote', 'textdomain' ),
        'categories' => array( 'quotes', 'text');
        'content'    => '<!-- wp:quote --><blockquote class="wp-block-quote hello-block"><p>Hello World of Blocks</p><cite>Carolina</cite></blockquote><!-- /wp:quote -->',
    )
);

The two categories; quotes and text, are placed inside an array.

To get the correct HTML code to use for your pattern, you can do the following:

  • First, create your block pattern in the editor.
  • Then open the editor toolbar, and select Code editor.

Locate your blocks, copy the code, and add it the content parameter in register_block_pattern.

<!-- wp:quote --><blockquote class="wp-block-quote hello-block"><p>Hello World of Blocks</p><cite>Carolina</cite></blockquote><!-- /wp:quote -->

Since your HTML contains double quotes, “, make sure that the content is wrapped in single quotes, or that you replace the double quotes with \”. Otherwise your code will break.

-The preview of the block is created for you automatically.

You can find more code examples in this Gist.

Custom CSS and identifiers for block patterns

It is worth noting that block patterns have no identifier once they are added to your content.

Even though the patterns have a name and a label, these are not applied to the code.

If you wish to add specific styles, or if you want to be able to identify your block patterns on the front, make sure that you add a custom CSS class while creating the pattern.

Naming block patterns

The name and label of the block pattern must be unique, because otherwise you will overwrite other block patterns.

The title; the visible name of the block pattern, is not unique. So to help identify your patterns, I recommend that you include your brand name, plugin- or theme in the title.

Categories
Beginners Quick guide

Adding custom block styles with PHP

Earlier this year I wrote two articles about how to add custom block styles with JavaScript and CSS files. With the new register_block_style PHP function in WordPress version 5.3, you can achieve the same result by adding custom block styles with PHP, with a lot less code and fever steps.

First, make sure that you have created a child theme. Do not edit the parent theme directly, or you will lose your changes when the theme is updated.

We will be using the same basic gallery block style as in our previous examples.

Open your child themes functions.php file.

To register your block style, copy the following code and add it to the file:

register_block_style(
    'core/gallery',
    array(
        'name'  => 'slug-hide-caption',
        'label' => __( 'Hide caption', 'text-domain' ),
        'inline_style' => '.is-style-slug-hide-caption figcaption { display: none; }',
    )
);

First, we are including the block name: Core/gallery.

Then we are adding three arguments: Name, label, and inline style.

  • Name is the CSS class that will be added to the block to identify it.
  • Label is the name that will be visible in the block’s style selector in the editor.
  • Inline_Style is the CSS code that will be applied to the block.

Remember to change the slug (the prefix), before you save your file.

The style should now be available in the editor:

A gallery block style with hidden captions.

By adding custom block styles with PHP, we can reduce the number of files that we need to include, since register_block_style() already includes the JavaScript and CSS for us.

As the name suggest, the CSS is added inline. Specifically, it is added to the wp-block-library stylesheet.

If you need to dequeue the wp-block-library stylesheet, you need to add the CSS to a different stylesheet that is loaded on the front.

Recommended reading

New Block APIs in WordPress 5.3

Categories
Beginners Quick guide

How to add a new default block style

When you add a new block style, you can also make it the default style in the editor.

Revisiting our gallery block where we hid the captions, we only need to add one new line: isDefault: true.

Our example codes would then look like this:

JavaScript:

wp.blocks.registerBlockStyle('core/gallery', {
	name: 'slug-hide-caption',
	label: wp.i18n.__('Hide captions', 'text-domain'),
        isDefault: true
});

Or, if you added the block style with PHP:

register_block_style(
    'core/gallery',
    array(
        'name'  => 'slug-hide-caption',
        'label' => __( 'Hide caption', 'text-domain' ),
        'inline_style' => '.is-style-slug-hide-caption figcaption { display: none; }',
        'isdefault' => true,
    )
);