Creating reusable patterns for WordPress Themes

As I’ve hinted at before one of the advantages of writing websites from scratch is that you get to be in control of everything. Of course as a site grows in complexity that can become a disadvantage too. Control, however, is addictive – and now I am using WordPress I am working hard at bending it to my will.

One of the big issues with WordPress is knowing where to start. There are literally thousands of themes and plugins available to do all manner of things. This probably means that almost anything you want to do someone has already provided – the problem is finding it! All of this leads me to revert to type and just do it myself. This week I have been creating my very own WordPress Theme. There is a very useful Full Site Editing lesson set. One thing that it doesn’t really cover is how to create reusable patterns.

Structure of a WordPress Theme

A WordPress theme is just a collection of php, json and html documents in a directory structure. The top level directory is named the same as the theme, and then underneath that there are a few more directories to contain the elements

MyTheme
  /parts
    footer.html
    header.html
  /patterns
    my-pattern.php
  /templates
    archive.html
    index.html
    page.html
    single.html
functions.php
style.css
theme.json

In a future blog I may delve into some of these in more detail, but for today I just want to look at my-pattern.php in the patterns folder.

Creating and using patterns

A pattern is a reusable block that we can pop into any post or page as many times as needed knowing that it will always look the same. Creating it is actually very straight forward – finding out how to was harder as almost everyone tells you how to do it in the Appearance Editor, but not how to save it as part of a theme.

Actually, starting it in the appearance editor turns out to be a very good idea. You can create the basic layout that you want in the drag and drop editor, and when you are happy with it pop into the code editor and copy the html you need.

In my case I wanted an image with a caption and a button underneath, all of them centred. I did this by using a group element to hang them all together. When I was finished, the code editor gave me the following

<!-- wp:group {"layout":{"type":"constrained","contentSize":"400px"}} -->
<div class="wp-block-group"><!-- wp:image {"align":"center"} -->
<figure class="wp-block-image aligncenter"><img alt=""/></figure>
<!-- /wp:image -->

<!-- wp:paragraph {"align":"center","style":{"spacing":{"margin":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
<p class="has-text-align-center" style="margin-top:var(--wp--preset--spacing--60);margin-bottom:var(--wp--preset--spacing--60)">Caption</p>
<!-- /wp:paragraph -->

<!-- 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 wp-element-button">Click Me</a></div>
<!-- /wp:button --></div>
<!-- /wp:buttons --></div>
<!-- /wp:group -->

This code is nearly everything we need in order to add it to the theme. The only thing missing is a php header which tells WordPress the name of the pattern and where to put it in the menu. Add this to the top of the code above, and save it as photo-block.php in the patterns directory of your theme.

<?php
/**
 * Title: Photo Block
 * Slug: gravid/photo-block
 * Categories: featured
 */
?>

As soon as that is added the pattern appears in the list of available patterns – in this case in the feature category. It is possible to add new categories, but that required registering the category in functions.php which I will leave for another day.