Here at WebDevStudios, we do quite a bit with Flexible Content Blocks in Advanced Custom Fields (ACF). If you aren’t familiar with the plugin, ACF allows for the creation of a multitude of custom meta field types using a graphical user interface (GUI) in the WordPress Dashboard. You can do almost anything with these fields—from simple text and URL inputs to searching for posts and pages and building image galleries.
ACF allows you to power your site with robust customization options, which you can use to create and manage dynamic pages. Instead of being locked into a set of page templates where the functionality and layout are tied directly to the theme’s files, building pages with ACF Flexible Content Blocks puts the power of customization into your hands as a site manager and editor. You can add, remove, and rearrange blocks as needed and have full control over the content within each of those blocks.
Sometimes, though, simply customizing the content within those blocks isn’t enough. Sure, it’s nice enough to be able to edit the title of a block or select a different set of Featured Posts to display. But, what if you don’t want to have to get that far into the weeds with customizing your pages and posts? What if you would rather set a category on a page or post and rely on the content blocks to figure out in which category your page resides and update the block content dynamically?
We recently discovered a use-case for such a situation and were able to find some fun and interesting ways to extend our standard ACF Flexible Content Blocks. Instead of requiring anybody to manually edit a set of content blocks already added to a page, we were able to add functionality into our blocks that look for the page’s category. Then, by the magic of wizards (or WordPress, I guess), we can filter the output of the block drastically cutting the time it takes to update an entire page of content.
So, what did we do and how can you use it, too? Let’s dig in and find out!
Our Block Code
Let’s start with a common case and a block which would be super handy to filter by a post’s category: Call To Action. This block ships with wd_s out of the box, so we’ll start first by looking at the markup driving it:
You may be asking yourself (or me, though I promise I can’t hear you), “Why would I need to dynamically filter that? Can’t I just edit the block’s contents?” Well, yes, you could just edit the block’s contents and be on your way. But, what if you use that same Call To Action on, say, a dozen pages which all share the same category? Suddenly, you realize you want to change the title of the Call To Action if that one specific category is set. Rather than having to edit a dozen individual posts, you could utilize a filter in your theme’s code to handle that work. That means less time editing posts and more time sitting back, sipping coffee and admiring a job well done.
How do you get there, though? First, let’s modify the block to be able to accept filters:
This starts off similarly to the initial block but there are some crucial changes in place. First, you’re creating a $default_args array immediately after you grab the block’s values. This stores the values you are saving to the block, like the title or button URL when you edit the page.
Directly after you set those items in the new $default_args array, you’re creating a second array called $block_args which merges the $default_args array with any potential array passed in via a WordPress filter. This means that if you never use the filter, nothing will ever change with regard to how this block works on the frontend. You’ll still edit the block as you normally would and see the expected updates when you save the page.
However, if you hook into _s_cta_block_args (as you’ll see later on), you can pass in your own custom values for all of the information you set in our $default_args array earlier in the snippet.
The final set of changes comes in how you output your data. Instead of simply calling the individual variables, like $title, you need to look inside of your $block_args array. Remember, even if you’re not passing in any filters for the current condition, you’re still creating a brand new array called $block_args which holds all of your data. So, instead of outputting $title you now need to output $block_args['title']. This is a small and subtle but pivotal change, otherwise the filtering won’t work once you get to that point.
Applying Our Filters
Now for the real magic. It’s all well and good to have the ability to filter the content, but how do you actually go about hooking in and filtering anything? With the magic of a WordPress filter, you can hook into the aforementioned _s_cta_block_args filter and run wild. You will need to be sure to test the conditions for these filters in various scenarios. If you simply hook into this filter without any conditional statement within it, the contents of the block will be altered everywhere it is used throughout the site.
So, it’s important to know when and why you need to filter your content. In this case, you’re going to check to see if the block is being used on a page or post which is set in a specific category. If it is not, you simply return your $block_args array. This means that you don’t alter anything and the block functions as it normally would. If you do find yourself on a page with that category set, though, the fun and excitement can begin.
You’ll need to pay attention to the array keys and be sure that they match what was set in your block’s template file, otherwise, you won’t see your filtered changes reflected on the frontend. In the example above, you’re filtering almost everything–the block’s title, the button URL and text, and you’re adding a CSS class so you can target this block with special styles sometime down the road.
Wrapping Up
And that’s it! You now have the ability to filter the content in a block without having to actually edit a page. This could be a massive time-saver if you realize that you need to change the URL of a button or link in a block that you’ve added to dozens of pages all which exist within the same category. Plus, once you’ve done it once it becomes second-nature to be able to add this same ability to your other existing blocks.
What other uses do you think you could come up with for filtering blocks this way?