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

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.

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 thedo_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.

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:

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:

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 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)