Howdy, WordPress developers and friends. I wanted to share some code that’s come in handy for me lately and a little information about using it.
While I don’t love everything about the block editor, I do love the concept of reusable blocks. In short, reusable blocks let you create and configure a set of blocks and then re-use that as many times as you want. Unlike patterns, you can manage a reusable block from a single location and then every instance of that reusable block on your site will be updated accordingly.
They’re perfect for things like call-to-actions, frequently updated content like announcements or promotions, testimonials and more.
Reusable blocks: Create once, use endlessly, update singularly.
Why add a reusable block to a template?
While you can certainly drop in a reusable block anywhere as you’re creating content, there are use cases for dynamically adding a reusable block at the theme template level.
For instance, let’s say we want to add some content at the beginning of each post, such as an affiliate disclosure or site-wide notification. Those are both perfect use cases for reusable blocks, but you wouldn’t want to manually add those blocks to every page of your site. Goodness, no!
Instead, you could dynamically inject them via template.
And that’s what we’ll take a look at doing for the remainder of this tutorial.
Birds-eye view of how we’re going to do this
Before we get to the actual code, I want to explain how things are going to go down. This is the solution that works for my scenario but it might not work for yours.
Get a reuseable block by its title (not its ID)
Create a function that retrieves the content (literally
the_content) of a reusable block using the block’s title as the identifier.
I’m using the
post_title in this case (versus the
id) because I’m working across multiple environments (local, development, staging, production) and the
id will vary between environments. The
post_title, however, is something I can easily match between environments.
Re-use this function a whole bunch
When I initially wrote the code to retrieve a reusable block by its title, I hardcoded the title. That was well and good until I realized I wanted to dynamically insert reusable blocks all over the place, not just in this one instance.
To that end, I’m passing the block title as a argument to the function that gets the reusable block. This allows me to reuse that function as many times as I want for as many blocks as I want. You’ll see how this works in a second.
Optionally filter the block content
I discovered there may be times I want to filter
the_content and other times I just want to return it without filtering it.
Consider this scenario: I’m using a social sharing plugin to hook icons after each post. If I filter
the_content from the reusable block, those social icons will appear after the reusable block (don’t want) AND at after the post (do want).
I can solve for this by NOT applying any filters to the content (which means nothing would fire on any hooks related to the content).
So my reusable blocks function takes a second argument, telling the function to return the content with filters applied (or not).
Let’s go to the code.
First, I’ll dump the code, then I’ll explain it.
We start with the
get_reusable_block() function. Per my explanation in the previous section, it takes two parameters: The first is the title of the reusable block and the second is whether or not we want to filter the results.
The first thing we’re doing in the function is using
WP_Query to get the post by its title.
Moving on to line 18, we’re getting out of there if there’s no reusable block with that title.
Moving on to line 22, we create a variable called
reusable_block and set it to the value of the
In line 24, we check to see whether our callable function wants a filtered response. If so, we kick
the_content to the
filter_reusable_block_content() function and
If we make it line 28, then our callable function does NOT want a filtered response, so that’s how we return it.
Ya with me?
Using our callable function in a template
get_reusable_block() function ready, we can add it to a site. I’m using the the word template, but you could apply this site wide via
functions.php or similar (in which case, you’d want to use conditionals to make sure the reusable block was added in the context you want, such as on a single post or an archive page).
For my example, let’s say I want to add a reusable block to a single post. I’ll crack open the
single-post.php template file (that’s named per the WordPress template hierarchy). I want to the reusable block to appear just below
the_loop, so I’ll dump it in like this:
echo get_reusable_block( 'The Title of My Reusable Block', false );
Of course, if you’re going to call that function, you need to make sure it’s available from wherever you’re calling it. I like to include a file with helper functions in my theme. So I might add the above file in my theme at
Then, when I want to use a function that’s housed in that file, I need to:
- Check if the function I want exists
- If not, load up the file where the function exists
- Use the function!
All in context, it might look like this:
There’s the down and dirty for creating a function that adds a reusable block to your content and an example of using that function in a theme template.
I don’t blog much these days because it’s time consuming to create thoughtful and thorough tutorials. I know I left some logic leaps in here for you to make. If you can’t quite connect the dots, please leave a comment and I’ll try to help.
If you found this helpful, please share!