colorful-tones
commented
2 years ago [Draft] Register and use block patterns
Proposed areas to cover (unorganized):
- Block patterns in themes
- How to include block patterns
- PHP registration of block patterns
- Using the
patterns/directory to register patterns - Important considerations when creating patterns
- Translations (i18n)
- Linking assets (images) - use
get_theme_file_uri() - Copy/pasting patterns from the block editor
- Including custom CSS classes in your patterns
- Using 3rd-party blocks
- Registering a custom pattern category
- Unregister a block pattern category
- Removing or hiding block patterns
Block patterns in themes
Block patterns are predefined block layouts. They offer a means to expedite and elevate the editorial experience by offering users a preset arrangement of blocks to start building right away.
Do you or your editors find themselves recreating patterns of blocks in the block editor? Then, converting those blocks into a pattern should save some time.
Let's jump in and learn how we can include them in a theme.
How to include block patterns
There are two methods for registering or including patterns in your theme and both approaches are compatible with classic and block themes:
patterns/folder (recommended for block themes)- PHP registration - uses the
register_block_pattern()
Using the patterns/ directory to register patterns
You can add a new patterns/ directory within the root of your block theme and place PHP files within to register patterns. Each individual PHP file would contain a different pattern, e.g. patterns/my-fun-pattern.php, patterns/another-pattern.php
The following is an example of a simple site footer pattern:
<?php
/**
* Title: Footer with text, social links.
* Slug: theme-slug/footer-default
* Categories: text, site-footer
* Block Types: core/template-part/footer
* Viewport Width: 1280
*/
?>
<!-- wp:group {"align":"full","layout":{"inherit":true}} -->
<div class="wp-block-group alignfull">
<!-- wp:group {"align":"wide","layout":{"type":"flex","allowOrientation":false,"justifyContent":"space-between"}} -->
<div class="wp-block-group alignwide">
<!-- wp:paragraph -->
<p>© <?php echo esc_html( gmdate( 'Y' ) ); ?> Your Company LLC · <a href="#"><?php echo esc_html__( 'Contact Us', 'theme-slug' ); ?></a></p>
<!-- /wp:paragraph -->
<!-- wp:social-links {"className":"is-style-logos-only"} -->
<ul class="wp-block-social-links has-icon-color is-style-logos-only">
<!-- wp:social-link {"url":"https://wordpress.org","service":"wordpress"} /-->
</ul>
<!-- /wp:social-links -->
</div>
<!-- /wp:group -->
</div>
<!-- /wp:group -->This pattern would be saved in the patterns/ directory in your theme, e.g. patterns/footer-default.php.
The title and slug properties in the pattern's header are required.
PHP registration of block patterns
You can use the register_block_pattern() function to register patterns with the init hook.
function theme_slug_block_pattern() {
register_block_pattern( ... );
}
add_action( 'init', 'theme_slug_block_pattern' );The register_block_pattern() function requires two properties in order to properly register a custom pattern:
title: A human-readable title for the pattern.content: Block HTML Markup for the pattern.
The following is a minimal example of a pattern with two buttons.
register_block_pattern(
'theme-slug/my-awesome-pattern',
array(
'title' => __( 'Two buttons', 'theme-slug' ),
'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'theme-slug' ),
'categories' => array( 'theme-slug-custom-category' ),
'content' => "<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} --><div class="wp-block-buttons"><!-- wp:button --><div class="wp-block-button"><a class="wp-block-button__link">' . __( 'Go shopping', 'theme-slug' ) . '</a></div><!-- /wp:button --></div><!-- /wp:buttons --></div></div>",
)
);You can create patterns of blocks within the block editor and then copy from the code editor, and paste them into the 'content' property. The 'content' property contains the markup that your pattern will output when inserted in the block editor.
The 'categories' property is optional and its value will assign your pattern to either a core or custom pattern category (See: Registering a custom pattern category below).
Important considerations when creating block patterns
Some key things to keep in mind when you're creating block patterns in your theme, which we'll cover:
- Translations (i18n)
- Linking assets (images) - use
get_theme_file_uri() - Copy/pasting patterns from the block editor
- Including custom CSS classes in your patterns
Translations (i18n) in patterns
Be sure to include the ability to translate strings when you're creating your block patterns. For example:
<!-- wp:heading -->
<h2>' . esc_html__( 'My great heading text', 'theme-slug' ) . '</h2>
<!-- /wp:heading -->Notice the esc_html__( 'My great heading text', 'theme-slug' ) in the above code sample. This allows builders to translate your strings into other languages.
Linking assets (images) - use get_theme_file_uri()
If you're including inline assets in your patterns then you can use the get_theme_file_uri() function to point to assets within your theme. Here is an example:
<!-- wp:cover {"url":"' .
esc_url( get_theme_file_uri( 'assets/images/snazzy-cover-image.png' ) ) . '",
"id":18,"contentPosition":"top center","align":"wide"}
-->Copy/pasting patterns from the block editor
A typical workflow for creating block patterns starts in the block editor. You add, group, alter all your blocks and then copy and paste the results into either the 'content' = => 'your content' if you're using register_block_pattern() function, or just raw if you're placing in a new PHP file within your patterns/ directory. You may consider escaping the string before pasting with a tool like: https://onlinestringtools.com/escape-string
Including custom CSS classes in your patterns
If you desire to add custom CSS classes to your pattern markup then you will have to use the className attribute. For example:
<!-- wp:group {"className":"call-to-action"} -->
<div class="wp-block-group call-to-action">
<!-- wp:heading {"level":3} -->
<h3><?php esc_html_e( 'My heading', 'theme-slug' ); ?></h3>
<!-- /wp:heading --></div>
<!-- /wp:group -->Note the use of "className":"call-to-action" and within the related, following <div class="call-to-action">. Both entries are necessary for this to work.
Using 3rd-party blocks
It is highly recommended that you conditionally load 3rd-party blocks within your patterns. Otherwise, the experience for rendering patterns can appear broken for end users. Here are two methods for conditionally loading blocks.
Conditionally load patterns when using register_block_pattern()
Oftentimes, well written plugins offer a parent class or function for you to check against when relying on its functionality. You can use either the function_exists or class_exists check within the init hook to check and register your pattern using register_block_pattern(), as so:
add_action( 'init', function() {
if ( function_exists( 'some_plugin_func' ) ) {
register_block_pattern();
}
} );Conditionally loading patterns when using patterns/ directory
Since patterns that are found in the patterns/ directory are auto-registered then we need to reverse the operation by deregistering it based on if the plugin is active.
For example, if we had patterns/footer-default.php in our theme:
<?php
/**
* Title: Footer with text, social links.
* Slug: theme-slug/footer-default
* Categories: text, site-footer
* Block Types: core/template-part/footer
* Viewport Width: 1280
*/
?>
<!-- block markup here -->If this pattern relied on a 3rd-party block then we would unregister it with unregister_block_pattern(), but we would have to hook it to our init hook, like so:
add_action( 'init', function() {
if ( ! function_exists( 'some_plugin_func' ) ) {
unregister_block_pattern( 'theme-slug/footer-default' );
}
} );Alternatively, if there were just a single 3rd-party block amongst many core blocks within a pattern that is loaded through the patterns/ directory. Then we could use PHP within the pattern to check:
<?php
/**
* Title: Footer with text, social links.
* Slug: theme-slug/footer-default
* Categories: text, site-footer
* Block Types: core/template-part/footer
* Viewport Width: 1280
*/
?>
<!-- some WP core blocks here -->
<?php if ( function_exists( 'some_plugin_func' ) ) : ?>
<!-- special 3rd-party block is here -->
<?php endif; ?>
<!-- some more WP core blocks here -->Keep in mind that the pattern will look differently without the block when the 3rd-party block is unavailable and the overall layout may appear broken depending on your styling.
Registering a custom pattern category
Organizing your block patterns into appropriate categories within the block inserter will help your users quickly find what they need.
You can register a custom category using the register_block_pattern_category() function. Here is an example:
if ( function_exists( 'register_block_pattern_category' ) ) {
register_block_pattern_category(
'theme-slug-query',
array( 'label' => __( 'Query', 'theme-slug' ) )
);
}This example registers a custom "Query" pattern category, which you can then reference and assign when you're registering your patterns:
register_block_pattern(
'theme-slug/my-custom-query-pattern',
array(
'categories' => array( 'theme-slug-query' ),
...
)
);If you do not assign a category for your block pattern then it will just be automatically assigned to Uncategorized in the block inserter.
Unregister a block pattern category
You can use the unregister_block_pattern_category() helper function to remove previously registered block categories. Typically, you'll want to call it within the init hook, like so:
function theme_slug_unregister_pattern_categories() {
unregister_block_pattern_category( 'theme-slug-query' );
}
add_action( 'init', 'theme_slug_unregister_pattern_categories' );The unregister_block_pattern_category() function accepts one argument: title, which is the name of the block pattern category to be unregistered.
Removing or hiding block patterns
By default, WordPress registers several block patterns and categories. However, theme developers can unregister some or all of these using the following methods:
remove_theme_support( 'core-block-patterns' );- removes all core patterns and should be hooked to either theinitor theafter_theme_setup()hooks. Or,unregister_block_pattern()- to unregister individual patterns. Example:unregister_block_pattern( 'core/two-buttons' ); // Removes core two-buttons pattern
Furthermore, you can disable the calling and displaying of patterns from the WordPress Block Pattern Directory within you theme by utilizing the should_load_remote_block_patterns filter.
add_filter( 'should_load_remote_block_patterns', '__return_false' );
zzap
TeBenachi
richtabor
carolinan
annezazu
What is the new page you are requesting?
A dedicated page about how to register and use block patterns. A page that will refer back to the block editor handbook page at https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/
How will this new page help you?
Right now, it seems that information about block patterns in themes is spread out over several pages: https://developer.wordpress.org/themes/?s=block+patterns
Block patterns can be added in classic themes and block themes, but they can register them in different ways. Both the PHP function and the method with placing patterns inside the patterns folder should be covered.
For help with writing the content, you can refer to the dev notes: https://make.wordpress.org/core/2022/05/03/page-creation-patterns-in-wordpress-6-0/ https://make.wordpress.org/core/2022/05/02/new-features-for-working-with-patterns-and-themes-in-wordpress-6-0/