Using Hooks within WordPress: a How-to and Why

Programmers

WordPress is a great system, but sometimes you just need a little customization. Templates offer some basic customization, but not always do they let you customize as much as needed. Don’t worry, WordPress understands. Back in WordPress 1.2.0 in 2004, they added in a neat function called a “hook” that allows you to move, add, and remove entire sections of plugins.

The Basic Setup

Hooks have three main functions:

do_action(”);

remove_action(”);

add_action(”);

do_action(‘actionName’);

This is the most basic hook, used by plugin authors and WordPress authors primarily. All “do_action”s are added into the plugin and/or WordPress’s core files and tell the computer to add in an action here.

remove_action(‘actionName’, ‘functionName’, 10);

The remove and the add are the two hooks you’ll use the most. The remove_action hook has 3 variables. The first is the name of the action, the second is the function that you’re removing from this hook, and the third is the priority – or the order functions are executed.

add_action(‘actionName’, ‘functionName’, 10);

Much like the remove_action, the add_action is set up to have three variables: the name of the action, the function we’re calling, and the order (or priority) we’re calling them in.

How it works using WooCommerce as an Example

Confused by those explanations? How about an example.

When Woocommerce creates their plugin, they used regular coding and a few hooks. For example, on the individual product page, they have a hook called:

do_action( ‘woocommerce_before_main_content’ ); 

Obviously, they added this line right before the main content of the products. Note that we can call the hook anything, but convention (and ease of use) leads us to name a hook according to where it is in the page. Let’s say we want to add something before the main content of the product. We’d use the “add_action” hook and add it either within the theme’s function.php or within a new plugin:

add_action(‘woocommerce_before_main_content’, ‘shopNotice’, 5);

Remember, the first variable in the action above references the hook we’re using, the second is a function, and the third is the priority. So if we add this hook, we need a function called “shopNotice” or we’ll get an error.

function shopNotice(){
   echo 'All items are 25% off using the code FANTASTIC';
}

Great! Now when the PHP gets to the line with the “do_action” hook, it automatically finds all the “add_action”s associated with that hook and runs them. Which means our little notice about a 25% off coupon shows on every product page at the very top.

Lastly, you’ll notice that I added a priority of 5 in that “add_action” above. Usually priorities go in multiples of 5, although to be honest, I’m not sure why. If you know or have a guess, leave it in the comments below! But how do we know that something isn’t already set to a priority of 5?

If you take a look at the single-product template within WooCommerce (or the Theme’s modification of that template), there are also some additional comments for you:

/**
 * woocommerce_before_main_content hook
 *
 * @hooked woocommerce_output_content_wrapper - 10 (outputs opening divs for the content)
 * @hooked woocommerce_breadcrumb - 20
 */
do_action( 'woocommerce_before_main_content' );

This is where they tell you what’s going on with this hook. There are two functions added to this hook – “woocommerce_output_content_wrapper” function with a priority of 10, and the “woocommerce_breadcrumb” function with a priority of 20. Since nothing has a priority of 5, we’re good to go!

Finally, let’s say we don’t like the breadcrumbs showing up on our product pages. In this case, we’ll use the remove_action hook.

remove_action(‘woocommerce_before_main_content’, ‘woocommerce_breadcrumb’, 20);

Again we reference the hook itself – woocommerce_before_main_content, and then reference the function we’re removing – woocommerce_breadcrumb, and finally the priority initially set – 20.

Summary

At first glance, hooks may seem complicated; but in reality, they’re a fantastically easy way to add and remove functionality quickly. Hooks in WordPress are just like paper clip chains in real life – they let you add or remove new functions whenever you want without ruining the entire chain.

Comments