A Newbie’s Guide to WordPress Hooks and Functions

When people start wanting to customize WordPress, specifically a theme like Thematic, or a plugin like WooCommerce, I always see questions like:

How do I add “something”, “somewhere”?

or

How do I remove “something” from “somewhere”?

or

How do I change “something”?

At first it is easy to think that adding a div to the #header is different from adding a menu to the #footer, but once you understand how filters and action hooks work, you’ll see these questions really all follow the same pattern. You just need to learn how to speak WordPress! Be patient with yourself, because you literally are learning a new language… especially if you aren’t already familiar with PHP.  I’ll be using examples for working with the [theme-link] but you don’t understanding hooks and functions and eventually filters will be handy in any WordPress project.  Let’s start…

What the heck is an Action Hook

Action hooks look like this:

do_action('this_is_the_action_hook_name');

In a plugin such as WooCommerce, if you investigate in the templates folder you will find all sorts of action hooks. The WooCommerce templates are extremely well-documented and tell you right there which functions are hooked into that action hook and in what order. In the theme, Thematic most of these are buried in the library/extensions folder.  In fact, in the actual templates (like index.php, category.php etc) you will see hooks that look more like:

// action hook for placing content above the index loop
thematic_above_indexloop();

But if you go searching for the definition of that function you will find that it is in content-extensions.php

/**
 * Register action hook: thematic_above_indexloop
 *
 * Located in index.php
 * Just before the loop
 */
function thematic_above_indexloop() {
  do_action('thematic_above_indexloop');
} // end thematic_above_indexloop

Now an action hook is sort of like a parking spot. Some are empty, some have cars on them. you can move the cars around, but the spots themselves stay put. When wordpress gets to an action hook, it will run all the functions that are attached to that particular hook. If it gets to a parking spot and finds a car, it will run that car. If not, then it will continue on to the next hook/space.

How To Add Any Function to any Hook

A completely fictitious example:

function function_you_want_to_add(){
echo "I heart bacon!";
}
add_action('destination_hook','function_you_want_to_add', $priority, $args );

The add_action line is doing the heavy lifting here, and always takes this same “form”…. it sort of reads like this in english:

Add the function called ‘function_you_want_to_add’ to the hook called ‘destination_hook’ in the order of $priority with some optional extra arguments called $args.

You can read all about add_action in the WordPress Codex (hint: there is a TON of info there, but I understand it can be overwhelming at first).

The $priority is always a number. It is like a traffic cop in the parking lot, or maybe just an orange cone. if more than 1 function wants to be on a particular hook the priority decides which goes first. If 2 cars wanted to be in the same spot, the one with the lower number priority would get ground level parking and the one with the higher priority would be stacked on top. Yay 3-d parking! Sorry, prepare yourself we are going to beat this metaphor to death. The default priority is 10, so if you don’t need to change that you don’t even need to define it in your add_action line.

Some hooks pass additional variables to the functions that operate on them, but this is pretty advanced so for an introductory primer we will ignore it.

Now, a practical example:

function function_you_want_to_add(){
echo "I heart bacon!";
}
add_action('thematic_above_indexloop','function_you_want_to_add');

If you add the practice example to your child theme’s functions.php you will see “I heart bacon!” appear on your blog page. Now leave that there and add the following just underneath it in your functions.php.

function kia_another_function(){
echo "Guacamole makes me happy!“;
}
add_action('thematic_above_indexloop','kia_another_function', 5);

Notice the priority number is 5. This means it has a lower priority number than the first function, which is 10 by default since we didn’t specify anything. When you reload your theme you should now see Guacamole makes me happy! on the blog index above the line about loving bacon. Bacon and guacamole together. It must be code heaven.

How to Remove Something From a Hook

removing stuff works a bit differently:

function remove_stuff(){
remove_action('hook_location','function_you_want_to_remove',$priority );
}
add_action('init','remove_stuff');

In english this sort of translates to:

When WordPress runs the init hook, please remove the function called “function_you_want_to_remove” that is located on the hook called “hook_location” with a priority of $priority.

init is just a WordPress hook. in fact, it is the one of the earliest hooks that run when WP starts whirring… it is like priority parking. You can see most all of the hooks that run in the WordPress process again at the Codex: Action Hooks  To remove something that had a specific priority originally, you must remove_action it with the same priority.  A good practical example would be removing the Thematic blog title.

function remove_thematic_header(){
remove_action('thematic_header','thematic_blogtitle', 3);
}
add_action('init','remove_thematic_header');

Paste the above into your functions.php, reload your child theme and poof the blog title is gonzo!

Moving the #access menu is another practical example, that combines adding and removing functions.  I’ll include it here because I see this question asked all the time.

function remove_thematic_header(){
remove_action('thematic_header','thematic_access', 9);
}
add_action('init','remove_thematic_header');
add_action('thematic_aboveheader','thematic_access');

Note that we don’t have to define thematic_access, because it already is defined by thematic. We can simply add_action it to a new parking spot.

Overrides R’ Us

Thematic has a bunch of functions built in that if you define them, they automagically replace the function thematic was going to add to a specific hook, with your custom function.  In WordPress parlance, this is called a pluggable function.  Many thematic functions can be overridden by copying a thematic function to your functions.php and altering the function’s prefix from thematic_ to childtheme_override_.  The overrides completely change the car that is parked on a particular parking spot but they don’t change its location.

For instance to override the thematic_blog_description you could put the following in your functions.php

function childtheme_override_blogdescription(){
echo "Evil laugh! Now your blog is only about bacon!";
}

Refresh your theme and you will see the blog description has been taken over by bacon. , which I think is neat.  Note that with pluggable functions you do not need to also call add_action.  Doing so will add the function twice.  Most functions in thematic have this override capability, but not all.  You can browse through the extensions folder (look but don’t touch the parent theme!)

If you see something like:

if ( function_exists('childtheme_override_blogdescription') )

That’s a sign that you can use the override feature.  The full IF statement reads something like:

If you define a child_theme_override function then Thematic will add your custom function to the appropriate hook instead of its own function.

Overrides are significantly more intuitive than filters, but filters can be more elegant: the scalpel instead of a broadsword if you don’t need to change the entire function.  However, this post is crazy long, so I will leave filters for the next part of series.

Additional Resources

To help you know what hooks are available in Thematic, here are 2 visual aids:

http://www.bluemandala.com/thematic/thematic-structure.html

http://visualizing.thematic4you.com

Additional Help

I’ve tried to make this as beginner-friendly as possible, but I’ve been doing this for a few years now and so it makes total sense to me. Please let me know in the comments if something about this tutorial is not clear so that I can make it better.

Also, I don’t have time to respond to specific support requests in the comments. If you have Thematic questions post them at the Thematic Forums or contact me for some premium support.

Thematic 1.0.1 Upgrade

After a long wait, Thematic 1.0.1 has been live in the WordPress repositories now for a couple of days now! And some issues are starting to crop up in the forum. So far the most recurring issues have to do with the menus. Oh menus, you never cease to cause trouble.

The problem is that thematic 1.0 underwent some major changes to be compliant with WordPress Theme Review Guidelines and the change with the most impact on menus in particular is our switch to properly enqueing stylesheets and scripts using wp_enqueue_stylesheet and wp_enqueue_script. This has led to some changes to existing functions and the removal of a few old filters that didn’t make sense anymore given the new approach. You can see the massive changelog in the readme.txt file that comes with Thematic, but really, its huge, so it would be easy to miss the ones that are effecting you.

I Upgraded and Now My Menu is Broken

We’re going to need to diagnose what went wrong based on what you used to be doing and what has changed.

* Changed: Filter thematic_dropdown_options.

Were you serving your own modified version of the thematic-dropdowns.js script to tweak the widths of the dropdowns, add arrows, or change the delay on the hover? If so, then you might have been filtering thematic_dropdown_options. This filter used to work like so:

[php]
function childtheme_dropdown_options() {
$newscript_uri = "\n" . ‘<script type="text/javascript" src="’ . get_stylesheet_directory_uri() . ‘ /scripts/thematic-dropdowns.js"></script>’ . "\n";
return $newscript_uri;
}
add_filter(‘thematic_dropdown_options’,’childtheme_dropdown_options’);
[/php]

in that you needed to return the whole script tag. That is no longer the case and now you need only to return the URL of the script like so:
[php]
function childtheme_dropdown_options() {
$newscript_uri = get_stylesheet_directory_uri() . ‘/scripts/thematic-dropdowns.js’;
return $newscript_uri;
}
add_filter(‘thematic_dropdown_options’,’childtheme_dropdown_options’);
[/php]

 

* Removed: Variable thematic_use_superfish. * Added: add_theme_support('thematic_superfish')

We’ve switched to using the WordPress function add_theme_support to determine whether to load the superfish scripts. Previously there was a filter called themtatic_use_superfish, that you could target to remove the dropdown scripts if you didn’t need them.
[php]
function childtheme_no_superfish(){
return FALSE; // we don’t want any of your vegetables!
}
add_filter(‘thematic_use_superfish’,’childtheme_no_superfish’);
[/php]

or if you were being super elegant, perhaps you killed the dropdowns with this:

[php]
add_filter(‘thematic_use_superfish’,’__return_FALSE’);
[/php]

But, we’ve ditched this filter in favor of using WordPress’ theme support feature. It is an easy switch. If you don’t want to load any of the superfish, dropdown scripts then you should now do it this way:
[php]
function childtheme_no_superfish(){
remove_theme_support(‘thematic_superfish’);
}
add_action(‘thematic_child_init’,’childtheme_no_superfish’);
[/php]

Note that thematic_child_init is a new action hook, that is specifically placed to remove any theme supports added by thematic.

* Removed: Filter thematic_head_scripts.

To be fair this one isn’t in the readme as far as I can see, but the problem is similar to the issue with thematic-dropdowns.js. Maybe you were using this filter to you maybe wanted to remove all the superfish and supersubs scripts because you don’t use dropdowns. Or perhaps you were adding your own scripts here.
[php]
function childtheme_scripts($scripts){
return FALSE; //we don’t want any of your vegetable scripts!
}
add_filter(‘thematic_head_scripts’,’childtheme_scripts’);
[/php]

or if you were adding a scripts of your own, maybe you did something like this:
[php]
function childtheme_scripts($scripts){
$scripts . = "\n" . ‘<script type="text/javascript" src="’ . get_stylesheet_directory_uri() . ‘ /scripts/thematic-dropdowns.js"></script>’ . "\n";
return $scripts;
}
add_filter(‘thematic_head_scripts’,’childtheme_scripts’);
[/php]

As before, we are now using using wp_enqueue_script, so thematic_head_scripts() is now only a function that is added to the wp_enqueue_scripts hook. You can remove it entirely the same way you remove any action:

[php]
function childtheme_remove_scripts(){
remove_action(‘wp_enqueue_scripts’,’thematic_head_scripts’);
}
add_action(‘init’,’childtheme_remove_scripts’);
[/php]

or possibly you were using the override:

[php]
function childtheme_override_head_scripts(){
// absolutely no bacon here
}
[/php]

However, that is a bit of a nuclear bomb approach and will also wipe out an important script for handling comment replies, which you may or may not need. But thematic is super granular and you can use a scalpel to kill the drop downs scripts quite easily instead of using a viking war hammer with the remove_theme_supportscrap of code from earlier.

If instead, you need to load more scripts, then you should make like Thematic and use wp_enqueue_script.

[php]
function childtheme_scripts(){
wp_enqueue_script(‘bacon-script’, get_stylesheet_directory_uri . ‘/scripts/bacon.js’, array(‘jquery’), ‘1.0’, true);
wp_enqueue_script(‘guacmole-script’, get_stylesheet_directory_uri . ‘/scripts/guac.js’, array(‘jquery’));
}
add_action(‘wp_enqueue_scripts’,’childtheme_scripts’);
[/php]

If you are wondering about why the two lines are different, you can read more about how to use wp_enqueue_script in the WordPress Codex:

* Changed: Function thematic_create_stylesheet to wp_enqueue_style.
* Removed: filter thematic_create_stylesheet.

I saw this come up in the forum already. Someone was using the thematic_create_stylesheet filter to add extra stylesheets to the header. Something along the lines of :

[php]
function childtheme_create_stylesheet($style) {
$style .= ”;
return $style;
}
add_filter(‘thematic_create_stylesheet’, ‘childtheme_create_stylesheet’);
[/php]

Well that filter is gone like a bowl of my famous guacamole, so if you need to add more stylesheets, then we’ll have to add them the updated way… which by the by, will work better with any caching plugins you might be using and prevents the same style from being loaded twice (like if you were loading the supersized script’s css and then you had a plugin that was also trying to load the same stylesheet).
Thematic is now loading the main stylesheet like so:

[php]
function thematic_create_stylesheet() {
wp_enqueue_style( ‘thematic_style’, get_stylesheet_uri() );
}
add_action(‘wp_enqueue_scripts’,’thematic_create_stylesheet’);
[/php]

I can’t think of too many reasons why you’d ever need to change that. Your theme will always need a style.css in order to be a valid theme. But if you need to add more stylesheets, it is going to work just like enqueueing scripts except we use a slightly different function, wp_enqueue_style.

[php]
function childtheme_create_stylesheet() {
wp_enqueue_style( ‘blue_style’, get_stylesheet_directory_uri() . ‘/styles/blue.css’ );
}
add_action(‘wp_enqueue_scripts’,’childtheme_create_stylesheet’);
[/php]

Oh Noes! My menu is still broken!

Well, head to the support forums and start a new thread. Here is a tip for getting better support: do NOT just say “my menu won’t work”. This tells me and the other volunteers absolutely nothing and makes it impossible to help you. Be precise when describing exactly what you are trying to accomplish, what you are seeing/experiencing now, compare that to what you were experiencing before hand, and tell us anything that you might have already tried. Screenshots can be helpful as can links to your live site.

Thematic Support Forums