Dynamically Adding a Reusable Block in a WordPress Template

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.

WordPress doesn’t (yet) surface reusable blocks in the admin area, making them harder to manage. There’s an easy fix for this and Bill Erickson’s got the code you can use to add Reusable Blocks to your admin menu.

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.

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 post_content.

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 apply_filters().

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

With our 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 /inc/helpers.php.

Then, when I want to use a function that’s housed in that file, I need to:

1. Check if the function I want exists
2. If not, load up the file where the function exists
3. Use the function!

All in context, it might look like this:

That’s it!

Wrapping up

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!