ThesisAPI → Hooks

Thesis Hook Syntax

Thesis Box Display IDThesis provides built-in hook locations on HTML Containers and other specialty Boxes like Post Boxes and Query Boxes.

To “activate” hooks for use on a Box, specify a Display ID on the Admin tab within the Skin Editor.

The 4 built-in hook locations and associated syntaxes are as follows (where $hook is the Display ID you’ve given to this Box):

  • hook_before_$hook
  • hook_top_$hook
  • hook_bottom_$hook
  • hook_after_$hook

Notice how the hook syntax follows a simple, predictable formula:

hook_[location]_[unique name]

Also notice the 4 default hook locations:

  • before — before the opening HTML tag
  • top — after the opening HTML tag
  • bottom — before the closing HTML tag
  • after — after the closing HTML tag

In addition to the above hooks, Thesis adds two other hooks to every page:

  • hook_before_html — after the opening <body> tag
  • hook_after_html — before the closing </body> tag

Of course, Thesis also includes the two standard WordPress Theme hooks—wp_head and wp_footer—on every page.

Where to Put Your Custom Hook Code

You can add custom PHP code to Thesis in two smart locations:

  1. /wp-content/thesis/skins/skin-name/custom.php

    Your Skin’s custom.php file; code you put in this file will only affect this particular Skin.

  2. /wp-content/thesis/master.php

    Your Thesis master PHP file; code you put in this file will affect every Skin on your Thesis installation.

Pro tip: You’ll need an FTP client to access these files, and you’ll need a text editor to edit them.

Code Example: How to Use Thesis Hooks

To illustrate how you might use the Thesis hook system, let’s add some welcome text above the header (which includes the nav menu and site title) in the Classic Responsive Skin.

According to Classic Responsive hook documentation, the header has a unique hook name of header. As we learned above, this gives us 4 potential hook locations: before, top, bottom, and after.

In this case, we’ll use the before location to add our welcome text:

add_action('hook_before_header', 'welcome_text');

function welcome_text() {
	echo "<p>Welcome, and happy ", date('l'), "!</p>\n";
}

With this custom code in place, visitors to your site will see a welcome message like this:

“Welcome, and happy Wednesday!”

You oughta know: We use standardized hook names wherever possible, but because of unavoidable HTML differences between Skins, we maintain specific hook documentation for each Skin.

How to Declare Hooks in Your Own Code

If you develop your own Skins and Boxes, you may wish to declare your own hooks at some point. The most powerful way to do this is by leveraging the Thesis API hook system.

To illustrate how this works, let’s say you’d like to declare a hook called my_banner_ad somewhere in your code. Here’s what that would look like with the Thesis API hook system:

global $thesis; // We must access the Thesis object first
$thesis->api->hook('my_banner_ad');

The Thesis API hook system invokes the WordPress do_action system, but it allows for hook-sniffing and intelligent event detection. Because of this additional power, we recommend using the Thesis API hook system whenever you declare your own hooks.