Introduction
The Genesis Framework is a remarkable development tool for building high quality WordPress sites quickly and competently. Understanding how the framework can help accomplish this goal can be somewhat elusive though. Detailed technical documentation is often lacking and walking through code to discover the hows and whys of things is sometimes the only way to learn.
I spend about an hour a day volunteering to answer questions on both the Studio Press Community Forum and on the Genesis WordPress Facebook page. I love helping people and teaching them to do things better. I don't always have the best answers, but over the last few years, I've literally provided thousands of responses to questions at all technical levels, questions that range from "How do I do such and such in CSS?" to "How do these filters work?"
Most recently, a poster on the Studio Press Community Forum asked a question that had me a little stumped and I gave an answer that worked to solve his problem, but it turned out not to be the best answer. In fact, after doing some research the original poster provided a better answer than the one I had given. This got me to thinking. Maybe I was being a little too lazy that day, or perhaps I was time constrained because of other commitments, but I could have walked through the Genesis code more deeply than I had and gotten to the better answer.
The better answer was to use one of the Genesis Dynamic Filters, but wouldn't it be nice if there were better documentation about Genesis Dynamic Filters? It would save a lot of code walking and bring us to problem solving solutions much faster. So this is the first of a series of articles to teach more about Genesis Dynamic Filters, what they are, and how to use them. If your preference is for visual learning, rather than reading, then I highly recommend Tonya Mork's Know the Code website. If you prefer reading, then please keep going. This series of articles focus on filters that can be used to customize Genesis.
WordPress Plugin API
When it comes to professional WordPress development, it is absolutely imperative we understand that the WordPress developers have given us a way to change system behaviors through events where we can register our own functionality. They've done this so we, as developers, can enhance the usability of WordPress and create a more feature rich environment. We can go in and tweak content, manipulate data, and do all kinds of fun things if we know how to use the event registry features of the WordPress plugin API. These events are known as hooks. Hooks are comprised of actions and filters.
Actions and filters are defined and executed in very similar ways, the primary difference is that a filter is a function that returns a value. Filters are primarily responsible for intercepting, managing, and returning content before rendering it to the browser, or saving data from the browser to the database. Actions are functions that are executed at specific points in the page rendering sequence. They do not return a value.
The two primary functions that we will look at in reference to Genesis is add_filter() and apply_filters().
- add_filter() registers your callback (function) to the specified event (filter hook). When the event fires, the callback is executed in the order of the specified priority. The default priority in WordPress is 10.
- apply_filters() fires the specified event, which means it loops through the event registry lookup table (array) and calls each registered callback one-by-one in the order of their priority. The callbacks are registered for this event using add_filter.
These functions let you make changes to themes or templates without editing the original file. However, the template or theme needs to have apply_filters() wrapped in an editable area before you can use add_filter() to make the edits via your own callback (function).
We'll dive more deeply into this concept as we continue through this tutorial. For now and for your convenience, here is a list of all WordPress filters, and there are a lot of them.
What are Genesis Dynamic Filters?
The Studio Press developers are very smart. They generally write very efficient, easy to understand code. While there are a few things I've seen in the Genesis code base that I may have done differently to provide greater efficiency or better readability, as a general statement, the code base is written for efficiency. One way the developers have done this is by applying filters dynamically. The Genesis code base includes several functions where apply_filters() is invoked based on specific contexts rather than being hard coded into the framework. You'll still find some hard coded apply_filters() in the framework, but the majority are applied dynamically.
We're going to examine how these dynamic apply_filters() are created in Genesis by looking at the code used to create structural wraps. But before we move into the code walk through, let me mention one PHP debugging tool that I find to be invaluable. That tool is Kint. It works very well with WordPress. I install it on every site I build while it is in the construction phase. It is an excellent replacement for var_dump(), print_r(), and debug_backtrace(). It is simply called by adding d() or ddd() in your code. We'll be using Kint as we walk through the Genesis code.
Genesis Structural Wraps
The first bit of code we're going to examine is the genesis_structural_wrap() function. This function is located in genesis/lib/functions/layout.php. Unless your child theme specifies otherwise, by default, genesis_structural_wrap() is called to create the <div class="wrap"></div> structure for the header, menu-primary, menu-secondary, footer-widgets, and footer.
The first thing to note is that this function is designed to receive 3 parameters: context, output, and echo. The context is the id of the element receiving the wrap as a child div. Initially, the output is either 'open' (default) or 'close'. Echo determines whether the output is echoed to the page or just returned to the calling function.
Now let's look at the functions that create the opening and closing tags for the site header container. Both of these functions are located in genesis/header.php
We're going to leave the genesis_markup() function for another article. Today, let's just focus on the structural wrap. As you can see, genesis_structural_wrap() is called in both the opening and closing genesis_header_markup functions. The first call passes a single parameter 'header', which is the context. Why are there no output and echo parameters sent? Because genesis_structural_wrap() defines defaults for these two parameters: $output = 'open', $echo = true. There's no need to pass 'open' if it is the default and, unless otherwise specified, echo is always enabled.
Because the focus of this article is dynamically created apply_filters(), take a look at line 37 in the genesis_structural_wrap() code.
See the {$context} variable wrapped in curly braces? This is the key to creating the Genesis dynamic apply_filters(). This is PHP syntax for creating a dynamic variable. This is also known in PHP as variable variables.
Every time genesis_structural_wrap() is called in header.php, the apply_filters() in this case is going to invoke any callback we've added to an event named genesis_structural_wrap-header with the add_filter() function. The "header" part of this event is the context passed as the parameter to genesis_structural_wrap(). The add_filter() that assigns the callback would normally be included in the child theme's functions.php.
As a default then, with this one function Genesis dynamically provides you with a way to manipulate the structural wrap for the header, menu-primary, menu-secondary, footer-widgets, and footer. Because these apply_filters() are created and named dynamically, their event names for add_filter() are:
- genesis_structural_wrap-header
- genesis_structural_wrap-menu-primary
- genesis_structural_wrap-menu-secondary
- genesis_structural_wrap-footer-widgets
- genesis_structural_wrap-footer
With this naming construct, all of these event names have the passed context appended to "genesis_structural_wrap-". Armed with this understanding, there's no reason to search through code anymore looking for filter hook event names relative to structural wraps. Simply just view the source code in your browser…
…and wherever you see a structural wrap, the context may be extrapolated from its parent element. On the next page we're going to walk through the code. The last page includes a few practical examples of how you can use this information to manipulate the Genesis structural wrap HTML output.
Code Walk Through
To get started, we're going to add a few Kint commands to the genesis_structural_wrap() function. Unless you are walking through an exercise like this one, it's never, ever a good idea to modify any Genesis Framework core code. This is being done here strictly for teaching purposes in a local sandbox environment. Always remove any debugging commands when you have finished your walk through.
The purpose of this debugging exercise is to see what happens when genesis_structural_wrap() is invoked, examine the values passed as parameters, and the output HTML produced by the function.
These following screen prints are Kint's output from the above commands. The first screen print is the output when genesis_header_open() is called in header.php. This is where you need to follow along in the code above. The first line output is '------- passed params -------'. I added these text headers so we can know at a glance where in the code we need to look. The next three lines are the context, output, and echo values. The genesis_header_open() function only passes the context parameter. The other 2 values are the defined defaults.
Next, we have a value for the theme supported wraps. In the code, the $wraps variable is an array. If the context is not a value found in the $wraps array, the function aborts and returns without doing anything. I've expanded this item so you can see the array contents. The genesis-structural-wraps array values are defined either in Genesis init.php or in your child theme's functions.php with add_filter( 'genesis_theme_support_structural_wraps', 'structural_wraps_callback' ). If defined in your child theme, your custom structural_wraps_callback() function returns an array. The values you see in this array in the screen print are the Genesis defaults. The values in this array will not change for any of the invocations of genesis_structural_wrap().
Finally, we see the output returned from genesis_structural_wrap() when the open parameter is used.
As with the opening function call, the closing function call outputs the closing div tag as can be seen below.
This same process holds true for every element where your theme supports structural wraps. Let's move on to the practical use of these dynamically created filters.
Adding and Removing Structural Wraps
Before we begin with the practical uses of the dynamically generated apply_filters(), let's touch on the important topic of adding and removing theme support for structural wraps. As mentioned earlier, Genesis defaults to structural wraps for the header, menu-primary, menu-secondary, footer-widgets, and footer. But what if you want to add a structural wrap to an element like site-inner, perhaps? Or, remove a structural wrap from the footer? The following code snippets will do this when added to your child theme's functions.php file:
Adding Your Own Custom Elements
Did you know that the Genesis Framework allows you to add structural wrap support for your own custom elements? As an example, take a look at the structural wraps supported in the Studio Press Minimum Pro theme:
Notice that Minimum Pro supports structural wraps for site-tagline and home-featured? There are no elements of these names in any default Genesis setup. These are custom elements added by the theme developer. The developer also chose to use the older nomenclature for nav and subnav instead of menu-primary and menu-secondary. That's not a problem though, because genesis_structural_wrap() translates the older tags into the new tags.
Because there are custom elements, the developer has to write the code to support them. This is the custom code from Minimum Pro for the site-tagline.
Notice the calls to genesis_structural_wrap(). What do these calls do?
Using Structural Wrap Filters
Let's say for some reason you want to add a child wrapper to the header area's structural wrap. You can use this code snippet:
Perhaps you want to change the structural wrap to something other than a div, like maybe a span. This snippet with do it:
Hopefully, you now have a better understanding of how these dynamically created apply_filters() work with Genesis structural wraps. I'm sure that some of you will come up with unique new ways to use them. Please share in the comments if you do.
Leave a Reply