Thesis 2 Hook Syntax

Core Hooks

Box Admin TabHooks in Thesis 2.1 are only available on rotator boxes (e.g., HTML Containers, Post Boxes, and Query Boxes); and you will need to specify a Hook Name on the Admin tab for the box in order to activate your unique hook.

The syntaxes for hooks are as follows (where $hook is the Hook Name 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 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 tag)
hook_after_html (just inside the closing tag)

Skin Specific Hooks

Predefined hooks may be available to you automatically, depending on the active Skin; for example, in the Classic Responsive Skin, the following elements each have 4 hooks associated with them:

— container
— header
— columns
— content
— post_box
— sidebar
— footer

If each of the above elements can be represented by $hook, then the 4 hooks available on each element are as follows:

hook_before_$hook (before the opening tag)
hook_top_$hook (just after the opening tag)
hook_bottom_$hook (just before the closing tag)
hook_after_$hook (after the closing tag)

So, out of the box, the Classic Responsive Skin provides 28 specific hook locations for you to use in its custom.php file, without your needing to assign any hook names to them yourself.

Where to Put Your Custom Hook Code

There are TWO places where you can add your custom hook-based PHP code (instead of one, as was the case in Thesis 1.x):

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

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

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

    Each Skin has a custom.php file in its own folder; code you put in this file will only affect this particular Skin.

Backward Compatibility

If you’ve been using Thesis 2.x for a while now, you may have noticed that the hook syntax described above looks very different than that which was used in earlier versions (and even that which was used in Thesis 1.x). We chose to introduce a more compact and consistent hook syntax in version 2.1, which will make them easier to remember when you need to use them.

Here’s how the old and new syntaxes compare:

If you’re using an HTML Container, the old and new syntaxes are as follows (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

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.