How to Customize Like a Pro with Thesis Hooks

This document is deprecated! The information on this page refers to a Thesis version that is now obsolete. Please visit the Thesis Docs for current documentation.

Hooks are the key to making just about any customization you want to Thesis and, ultimately, to WordPress. Thesis features a simple hook system that is essentially an API—a set of basic commands that you can use to add to, subtract from, and modify the functionality of your Thesis installation.

The beauty here, however, is that you don’t have to be a programmer or coder of any sort to understand and utilize the Thesis hook system. If you can cut and paste, then you shouldn’t have any trouble making basic, effective (and best of all, futureproof!) customizations to your theme.

By leveraging hooks, you can isolate all of your custom HTML changes to a single file—custom_functions.php. Without question, this is the most powerful and efficient way to run your site with the Thesis WordPress framework.

Using the Thesis Hook System

More than likely, your preferred use of hooks will be to insert your own custom bits of HTML into specific locations around the theme. Conveniently, you can accomplish this from within your custom_functions.php file, and the entire process consists of just two steps:

  1. construct a simple function to house your custom HTML
  2. tell Thesis where to place your custom code by specifying the appropriate hook

Sounds easy enough, right? To illustrate the specifics, we’re going to look at a few examples, but before we get into that, you need to know the two basic commands that will allow you to work with both Thesis and WordPress hooks.

Hook Commands

Hooks run whatever functions you tell them to run, so ultimately, working with them is a pretty straightforward process. You can add a function to any hook by using the add_action() command, which takes the following form:

add_action('hook_name', 'your_custom_function');

Hooks can run any number of functions, and in many cases, you may want to run two or more functions in a single hook location. In order to run a second (or third, or fourth, etc.) function at a particular hook, all you need to do is add a second add_action() call:

add_action('unique_hook_location', 'your_custom_function_1');
add_action('unique_hook_location', 'your_custom_function_2');

By default, Thesis uses a few of its available hooks, and occasionally, you may want to un-hook default functions, move them around, or replace them with your own functions. In this case, you’ll need to use the remove_action() command:

remove_action('hook_name', 'function_you_want_to_remove');

Now that you know the two commands for working with hooks, you can dive into some examples and learn the specifics of hook interaction.

Example 1: Make Your Header Display Above Your Nav Menu

The goal of our first example is simple: we’d like to rearrange the top of our site so that the header appears above the nav menu. By default, Thesis uses hooks to position both the nav menu and the header, as seen in launch.php1:

add_action('thesis_hook_before_header', 'thesis_nav_menu');
add_action('thesis_hook_header', 'thesis_default_header');

Our goal is to have our header display above our nav menu, but right now, the opposite is true because the nav menu is hooked into place just above the header (using thesis_hook_before_header). In order to solve this problem, all we have to do is move the nav menu to a hook that exists immediately beneath the header… But which hook will we use for that?

Generally, most Thesis hooks exist in pairs, as seen in the hook reference list. For instance, there are two hooks surrounding the header:

  • thesis_hook_before_header
  • thesis_hook_after_header

Since our goal is to move the nav menu beneath the header, all we have to do is unhook the nav menu from above the header, and then simply reposition it with a new hook, like so:

remove_action('thesis_hook_before_header', 'thesis_nav_menu');
add_action('thesis_hook_after_header', 'thesis_nav_menu');

Example 2: Add a Popular Posts Widget to Your Sidebar

In our second example, let’s assume that we’d like to place a popular posts widget at the top of Sidebar 2. Example 1 was simple because we didn’t actually have to create any content—we just moved the nav menu to a different hook. However, in this case, we actually need to figure out a way to create a sidebar widget containing a list of our most recent popular posts, and then we have to hook that widget into place atop Sidebar 2.

Fortunately, Thesis comes equipped with a handy function (thesis_widget_recent_posts) that can generate a recent posts widget from any category, so we’re going to be making use of this to generate our popular post list. Here’s what the function looks like:

thesis_widget_recent_posts('category slug', 'widget title', 'number of posts to show');

In the above snippet, category slug, widget title, and number of posts to show are all optional parameters, but we’ll need to specify at least a category slug and widget title in order to make this function show only items from our “Popular” category. Here’s how we do that:

thesis_widget_recent_posts('popular', 'Popular Posts');

In a perfect world, we’d be able to hook the above function into place, and our work would be done. Unfortunately, the add_action and remove_action commands do not allow us to specify parameters for the functions we call, and without parameters, the above function is useless.

Clearly, we’re going to need a workaround, and in this case, the solution happens to be quite simple. All we need to do is wrap the function call above inside a new, parameter-less container function, and then we can hook this new function into place. Check it out:

function custom_popular_posts() {
    thesis_widget_recent_posts('popular', 'Popular Posts');
}

Because our new function does not contain any parameters, we can hook it into place wherever we want. In this case, our goal is to add a popular posts widget to the top of Sidebar 2, so we’ll need to use the thesis_hook_before_sidebar_2 hook to get this new widget to appear in the correct location. Here’s the actual reference that we’re going to use:

add_action('thesis_hook_before_sidebar_2', 'custom_popular_posts');

Putting it all together, here’s the chunk of code that you need to add to your custom_functions.php file to have your popular posts list appear in Sidebar 2:

function custom_popular_posts() {
    thesis_widget_recent_posts('popular', 'Popular Posts');
}

add_action('thesis_hook_before_sidebar_2', 'custom_popular_posts');
  1. Your launch.php file is located at /thesis/lib/functions/launch.php. ↩