wpthemedetector-logo
WordPress Theme Detector Blog
WordPress Actions

Add functions to your WordPress child theme (4) – WordPress Actions

13 comments

In the previous tutorial of this series we introduced WordPress hooks and saw the differences between WordPress Actions and WordPress Filters. It´s time now for some action!

This post is intended for making clear what WordPress actions are, how they work, how to use them and how they are hooked to the right place or event. So if you finish the reading of this tutorial without having all that perfectly clear, or if you end up still thinking that WordPress actions are hard to deal with, it will all be my only fault because my motivation to write this post is to get just the opposite effect.

The Action Hook itself: The do_action function

Remember what I said on my previous post about the Terminology Confusion when referring to action and filter hooks? Let´s make concepts clear from the starting point:

The real action hook is none other than the string included in the $tag variable of the do_action($tag) when this function is found at the right place, thus marking an event for which we want our code to fire a particular action (or even more than one).

A bit messy? Not at all, as you will soon realize. Let´s see in detail what all this means.

If you look at the different php template files included in your WP theme, you will find here and there various examples of WP actions hooks. They come in the form of a do_action function.

By definition, the do_action($tag) function invokes all functions attached to the action hook $tag.

A common example

We will begin with a standard WordPress action hook: wp_footer.

A good practice for every theme developer is to place the following code in the footer of the theme:

<?php
do_action( ‘wp_footer’ );
?>

Or, as we will see in a moment, just this:

<?php
wp_footer();
?>

That way, when that part of the code is reached, WordPress will look for any functions registered for the wp_footer hook, and will then execute them in the order desired (more on this in a moment). Which means that, without ever touching the core WP code, we are free to construct functions that will be executed every time the WordPress code reaches the footer of our page (or at least we should be able to do so, as long as our theme is properly coded).

Well, I used the term “good practice” above, but including the wp_footer hook should really be considered a must. It is good practice for theme developers to include hooks in as many places as possible, at least where somebody could think of including a custom function.

The wp_footer hook is very widely used for placing some particular pieces of code before closing the body of our page. For example it´s used by plugins to inject scripts in the site html footer, or it could also be used to place special tracking codes like the ones used by Google Analytics. And a perfect example of functionality hooked to wp_footer is the WordPress admin bar that you see in top of your page when you are logged in.

But let us see this hook in the real world.

Got a wrench at hand? Let´s take a look at the Twenty Fourteen theme. More precisely, let´s look at how the footer.php template file is coded:

Can you see the line <?php wp_footer(); ?> down there, right before the closing body tag?

It doesn´t look like a do_action function at first sight, but it actually is a very simple WP core function (included in the general-template.php file inside the /wp-includes/ folder of your WP installation), as simple as this:

function wp_footer() {
do_action('wp_footer');
}

Which means that the wp_footer function is an action hook.

How to “get hooked”: The add_action function

The way to hook our functions to the event marked by the hook we´re interested in is by means of the WordPress core function add_action. In its simplest form, it looks like this:

<?php add_action( $hook, $function_to_add ); ?>

According to the WordPress Codex,  it “Hooks a function on to a specific action. More specifically, this function will run the function $function_to_add when the event $hook occurs“.

It couldn´t be simpler, could it? Well, you might not see it that clear now until you see this stuff working. But don´t worry, you´ll do in just a moment.

Before that, let me just explain that when I wrote “its simplest form” it was because the add_action function can accept optional arguments, and it can also handle optional priorities. So, for your information, the complete form of this function would be like this:

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

That´s why I said before that WordPress will look for any functions registered for a particular hook and execute them in the desired order. Quoting the WordPress Codex again, the $priority parameter is “Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action“. If no priority is specified, WordPress will assign the default value: 10.

Let´s play with action hooks

I know that by now you are tired of definitions and would like to get some action. Am I right?

But hey, wait a moment. I think WordPress actions are playing hide-and-seek with you!

Didn´t you see any other action hook in the footer.php template file from Twenty Fourteen theme above?

Yes, you got it right! There´s yet another one in this line:

<?php do_action( 'twentyfourteen_credits' ); ?>

Now that you´ve found it, we´re going to play with that action hook. You´ll notice that it is placed inside a div with a class named “site-info”, right before the line that generates the “Proudly powered by WordPress” message and link that appears at the footer of your site when you use Twenty Fourteen.

I´ll tell you what we´ll do: We are going to place our own credits before that message, and we´ll do it without touching the original footer.php template file, simply by hooking a custom function to that hook we´ve just discovered.

We will be using a custom function that I´ve already used in my post Add functions to your WordPress child theme (2) – Create a new function. Here it is:

We need to pass two arguments to this function (the name of the copyright claimer to be displayed and the starting year of the website), and then the function gets the current year, determines whether the current year is different from the starting one and constructs the text line that will constitute our copyright notice by including the copyright symbol (©), the year range (for example 2010 – 2013, or just 2013 if our site is new) and the claimer (for example your name).

If you have any doubts about this code, the way this function works is fully explained in the post I mentioned and linked above (I´m using here the function I called “Approach #1” on that post).

Once you add that function to the functions.php file of your child theme, you will only need to make it work whenever WordPress reaches the appropriate hook (twentyfourteen_credits in this case). You can do so for example by adding these lines of code to your functions.php file as well:

Let me explain what I did here:

  • First, I´ve created a new function my_custom_credits() that just echoes the text returned by the function my_updated_copyright($first_year, $owner) giving it a little styling: a 15px space to separate this text from the next (“Proudly powered by WordPress”).
  • I´ve provided the values I want to be displayed on the footer (in this example I´ve used 2010 for $first_year and “My Name” for $owner).
  • And, finally, I´ve hooked the new function my_custom_credits() to the twentyfourteen_credits action hook by using add_action( $hook, $function_to_add ); as we saw before.

Does it work? Sure it does, here is the resulting footer on my Twenty Fourteen test site:

wp-actions-footer

Of course, if you want to use this function hooking it to twentyfourteen_credits or to whatever other suitable hook in any other theme you may be using, remember to replace the values 2010 and My Name with the year you launched your site and your name or that of your business.

Conclusion

In this tutorial we have learned what WordPress actions are and how they work, and we have learned how to use them by means of an example.

By now all your fears about WordPress actions should be gone (or at least most of them). Otherwise, I would have failed like I said at the beginning of this post.

Let me know about your progress with actions hooks through the comments. And if you think that anything is not clear enough, let me know as well.

Luis Alejandre

Luis is the creator of the WPThemeDetector tool and the chief editor of this blog. You can read more about Luis in our About page.
Liked this post? Please share it!

13 Comments

  1. COOL!!!

  2. Very helpful description i found there.Mostly first time i was confused about hooks and action after using all function now i enjoy working with hooks and action. Nice one.

  3. Thank you for this article. would you know where it is possible to find a list of all action hooks available for a given theme ? More specifically, the TwentyFourteen theme ?

  4. Thanks for some very informative articles on hooks and functions. I was recently working with a theme which included options for adding 3 social media links and wanted to add an additional one. Read your articles and bingo all done.

    One question, is it possible when adding an additional control into a customise theme section to tell wp where to add it? In the example above I added an additional field into a ‘theme options’ section in customise and it’s at the top of the theme options section and I’d like to place it below the other similar options on this section.

    Hope that makes sense.

    • Hi, Tim.

      Of course it makes sense. And of course it is possible. You just have to give your new control a lower priority (higher priority number). Priority is one of the args in:

      $wp_customize->add_control($id, $args);

      You can find more info in the WordPress Codex.

  5. Thanks Luis. Unfortunately the other controls didn’t seem to have any priority set. I tried 10 and it was at the top of the list and 11 and it was at the bottom of the list. I just wanted it one from the bottom. Right at the bottom is logically better though.

  6. Thank you for this article. Has any one found more other actions hooks?

  7. Very brilliant tutorial. I would like to continue reading with chapter 5 about filters. Is there a chance to read it in the near future?

Submit a Comment

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