WordPress Action Hooks – the simplified version

There’s no point in hacking around with the WordPress core code. You still see people doing it sometimes and happily showing off their results, but it just isn’t a good idea. Nobody else can use it without making the same hack(s), which aren’t carried through an automatic update anyway.

WordPress action hooks allow you to access the functions of the core WP code, without messing around with that code. It’s the basis for most plugins (the whole business essentially started out as the plugin API), but themes are using them more and more and there’s no reason not to… do_action/add_action are also the means of getting external scripts, CSS, javascript/jQuery correctly on the page.

WordPress pre-dates PHP5 and the improvements available in terms of Object-Orientated Programming (OOP). So, while there are obviously classes and objects in there, everything has a flow – once the PHP engine has compiled the code, it’s run from top to bottom – it’s procedural, as they say.

Instead of adding a method to a class, or extending a class with another class, there are points in the action where the possibility of doing something is left open – action hooks – either predefined, because they’ve been put in the core code, or you can create your own.

The means of doing it involve a couple of functions…

do_action() and add_action()

Simply, do_action() is the function to create an action hook.

Whereas add_action() is tacking actions onto a given hook and always refers to a function that will called at that point.

<?php do_action( $tag, $arg ); ?>

<?php add_action( $tag, $function_to_add, $priority, $accepted_args ); ?>

The $tag is the action hook itself, a description of “where” – at what point in the action…

As an example, we can create an action hook that outputs some content on the home page just before the Loop of posts is output.

so in home.php

 <?php

 do_action( 'before_the_index_loop' ); 

    if (have_posts()) : while (have_posts()) : the_post();
     //etc etc
?>

and in functions.php

add_action( 'before_the_index_loop', 'my_helloworld_display' );

function my_helloworld_display(){

 echo "<p>This is my hello to the world</p>";

}

At the point where it reaches the action hook ( ‘before_the_index_loop’ ) put there by the do_action, it finds a function (my_helloworld_display) to call and calls it.

(Or you could put this in index.php and test whether it’s running as the home page by using is_home().)

Priority

Everything has an order – lower to higher – and if you don’t specify it, the default value of an action is 10.

So here, as an example, we can add an action earlier in the document flow that’s actually going to be run after the next add_action.

add_action( 'my_helloworld', 'my_second_helloworld_display', 20);
add_action( 'my_helloworld', 'my_helloworld_display');

function my_second_helloworld_display(){
 echo "<p>Hello again to the world</p>";
}

function my_helloworld_display(){
 echo "<p>Hello to the world</p>";
}

Will produce:

Hello to the world
Hello again to the world

Accepted arguments

In, say, header.php, we can place a hook with some arguments:

do_action( 'my_details', get_bloginfo('name'), get_bloginfo('description'));

While in functions.php we’re going to expect 2 arguments to be passed to the function.

add_action( 'my_details', 'my_details_display', 10 ,2);

function my_details_display($name, $description){

 echo "<p>This is the name of my blog: {$name} and this is its description: {$description}</p>";
}

(Of course, this is just for the very simple example of it, to show how arguments are passed to any function referenced by an add_action – the whole process could have been short-cut just by putting bloginfo(‘name’) on the page…)

In practice, it can be slightly tricky to find out the what and how many of arguments are being passed to predefined action hooks – that’s when you do have to look into the core code.

And just for experiment (on a development site, don’t leave lying around on anything live)

add_action('wp', 'my_vardump');

function my_vardump($query){
	global $post;
	print_r($query);
	print_r($post);
}

Just to see what’s available to play with…

There are a lot of action hooks strewn around the place in WordPress code already – not all of them are terribly well-documented, (it’s a large job). The thing to do is to consult first the Codex for the main list of hooks and then experiment, adding your own hooks and making use of those already there. At least, action hooks do simplify the whole process – it’s only one line of code to comment out if things start going wrong.