A Guide to the Actions API

14 Comments

WordPress theme frameworks have been all the rave nowadays, and rightly so. Everybody’s either using one or rolling their own flavor. Theme frameworks introduce several new concepts to theme authoring that till now, only plugin developers have been taking advantage of. In this article, I’m going to introduce you to the actions API, and break it down so you can understand how it all works.

If you don’t already know about action hooks, they’re simple little functions that act as a placeholder to allow other functions to “hook” into that particular spot where the placeholder function was called at. Here’s an example to demonstrate that:

wp_head() an action hook which is located in your theme’s header.php is a prime example of how action hooks work. wp_head is located in your theme’s header.php. Let’s take a peak at the source:

/**
 * Fire the wp_head action
 *
 * @since 1.2.0
 * @uses do_action() Calls 'wp_head' hook.
 */
function wp_head() {
	do_action('wp_head');
}

As you’ll notice, there’s nothing actually in wp_head that prints out any scripts or meta tags. wp_head simply calls a do_action function with the first parameter being wp_head. And that’s where the magic lies: do_action();

In order to create an action hook, you simply need to create a placeholder function that calls do_action(); with the first parameter being the name of the desired hook. Typically, you’d want the name to be exactly what the function name is, but it can be anything you’d like; as long as the name isn’t already in use.

Now here’s how the magic works: Once you call the do_action('wp_head'); with the first parameter being the name of the desired hook, WordPress registers this call into the system. With the hook now registered into the system, we can now call the add_action(); function allowing us to hook into wp_head.

Viewing the source of default-filters.php where WordPress hooks into the wp_head action hook reveals this:

add_action('wp_head', 'wp_enqueue_scripts', 1);
add_action('wp_head', 'feed_links_extra', 3);
add_action('wp_head', 'rsd_link');
add_action('wp_head', 'wlwmanifest_link');
add_action('wp_head', 'index_rel_link');
add_action('wp_head', 'parent_post_rel_link', 10, 0);
add_action('wp_head', 'start_post_rel_link', 10, 0);
add_action('wp_head', 'adjacent_posts_rel_link', 10, 0);
add_action('wp_head', 'locale_stylesheet');
add_action('wp_head', 'noindex', 1);
add_action('wp_head', 'wp_print_styles', 8);
add_action('wp_head', 'wp_print_head_scripts', 9);
add_action('wp_head', 'wp_generator');

More than a dozen functions get hooked into wp_head by default. You’ll notice that the first parameter is wp_head, with the second parameter being a PHP function. What add_action does, is register those PHP functions to the wp_head action hook. So whenever a do_action('wp_head'); is called, WordPress checks to see if any PHP functions are registered to wp_head, and if so, execute them. And that’s how the WordPress actions API works.

Now why go through all that trouble when WordPress could have easily included all these functions into the actual theme itself? Well for one, the actions API makes your theme future proof. If you noticed right above the wp_head function, there was a comment stating that it was there since WordPress 1.2.0. That’s a pretty long time, and I can assure you that all those PHP functions registered to the wp_head hook weren’t there back in those days. Using the actions API, WordPress was able to use one placeholder function and hook in functionality later down the line when needed, like feed_links_extra, which was introduced in WordPress 2.8.

Using the actions API, you can also remove PHP functions registered to a particular hook using remove_action();

remove_action( 'wp_head', 'wp_generator' );

The first parameter indicates which hook we’re targeting, and the second is the actual PHP function we’d like to remove. This function is useful if your using a theme framework and would like to remove some of their default behavior.

So to recap, the actions API allows you to create placeholder functions in your template files, allowing other functions to hook into that particular spot just by registering them using the add_action call. To read more on this topic, here are a few links that also explains the matter:

The actions API is exactly how plugins are able to add features and functionality to WordPress as those little do_action() calls are made all throughout the WordPress core. Nowadays, themes are starting to get more advanced, so they started making use of the actions API to allow more flexibility and future proof. In the next article, I’ll demonstrate some creative uses for action hooks that you can use in your themes.

14 thoughts on “A Guide to the Actions API

  1. Pingback: links for 2009-06-15 | Links | WereWP

  2. Pingback: Wordpress News - A Guide to the Actions API — WPCandy — WordPress Themes, Plugins …

  3. Pingback: A Guide to the Actions API — WPCandy — WordPress Themes, Plugins … | bllogger

  4. Pingback: Cell Mobile Guide » A Guide to the Actions API — WPCandy — WordPress Themes, Plugins …

  5. Pingback: Daily Links for Tuesday, June 16th, 2009

  6. Pingback: WordPress & Blogging Articles for june 16 2009 | WPStart.org - WordPress themes, plugins and news

  7. Pingback: Creating Widgets in WordPress 2.8 with the Widget API — WPCandy — WordPress Themes, Plugins, Tips, and Tricks

  8. Pingback: Theme Playground | Community Roundup: The Pay-for-Plugins Edition

  9. Pingback: Creating Widgets in WordPress 2.8 with the Widget API | Fresh News - Blog Design, Wordpress, Blogger, and Web Development

  10. Pingback: WordPress & Blogging Articles for june 16 2009 | Quest For News, A TUTORIAL Base

  11. Pingback: EG-Links: Revue de blogs | Emmanuel GEORJON

  12. Pingback: A Guide to the Actions API — WPCandy — WordPress Themes, Plugins, Tips, and Tricks

Leave a Reply

Please note that WPCandy is a moderated community.

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>