When people start wanting to customize WordPress or specifically, Thematic, 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 Thematic Theme Framework 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');
Now in 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.
