Thesis Hook Syntax

Box Admin TabThesis provides built-in hook locations on rotator Boxes (e.g., HTML Containers, Post Boxes, and Query Boxes). To “activate” hooks for use on a particular Box, specify a Display ID on the Admin tab within the Skin Editor.

The syntaxes for hooks 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 how Thesis automatically creates 4 hooks for core rotator elements: before, after, top, and bottom.

The before hook fires before the opening HTML tag for the Box in question, and the after hook fires after the closing HTML tag. The top hook fires immediately after the opening HTML tag, and the bottom hook fires immediately before the closing HTML tag.

In addition to the above hooks, these two are also available to you (note that you cannot specify your own unique hook name for them):

  • hook_before_html (just inside the opening <body> tag)
  • hook_after_html (just inside the closing </body> tag)

Where to Put Your Custom Hook Code

There are TWO places where you can add your custom hook-based PHP code:

  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 Control PHP file; code you put in this file will affect every Skin on your Thesis installation.

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

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.

Backward Compatibility

The Thesis hook naming syntax has evolved and become simpler over time. Here’s how the old and new syntaxes compare:

Here are the old and new syntaxes for an HTML Container (where $hook is the name you’ve given to this Box’s hook):

  • thesis_hook_before_container_$hookhook_before_$hook
  • thesis_hook_container_$hook_tophook_top_$hook
  • thesis_hook_container_$hook_bottomhook_bottom_$hook
  • thesis_hook_after_container_$hookhook_after_$hook

And here are the old and new syntaxes for Post Boxes:

  • thesis_hook_before_post_box_$hookhook_before_$hook
  • thesis_hook_post_box_$hook_tophook_top_$hook
  • thesis_hook_post_box_$hook_bottomhook_bottom_$hook
  • thesis_hook_after_post_box_$hookhook_after_$hook

Important: Even though we retained the old hook syntax in 2.1 for compatibility reasons, we do plan to remove the old hooks in either 2.2 or 2.3 — so, you should migrate all of your hook-based PHP code to using the new syntax as soon as possible, and rely only on the new hook syntax for any future customizations as well.