WordPress Actions, Filters, and Hooks : A guide for non-developers
When I was learning how to use hooks in WordPress and the Customizr theme, I got tired of searching for articles that explained actions, filters and hooks, in simple terms. Most articles are complex, are written for developers, and start like this:
Actions and filters allow you add your own functionality or modify your site’s behaviour by hooking a callback function onto a specific tag in the core code, setting priorities and using parameters and arguments passed to the callback function.
The basics
- Actions allow you to add extra functionality at a specific point in the processing of the page—for example, you might want to add extra widgets or menus, or add a promotional message to your page.
- Filters allow you to intercept and modify data as it is processed—for example, you might want to insert another CSS class in a WordPress HTML element, or modify some of your pages blocks.
Getting down to details
When Gill comes by, tell her to go to the store to get some paint. When Jack comes by bragging about how great he is, get him to say that Gill is better.
Actions:
When Gill comes by, tell her to go to the store to get some paint.
// Send Gill to get paint add_action( 'after_gill_arrives' , 'send_gill_to_get_paint', 10 , 2 ); function send_gill_to_get_paint( $gill_has_keys, $gill_has_car ) { // If $gill_has_keys and $gill_has_car are both true if ( $gill_has_keys && $gill_has_car ) { echo 'Gill, please go to the store and get some paint. Thank you!'; } }<br>
What did we just do there?
- We watched for a particular thing to happen—Gill having arrived; in programming terms the ‘after_gill_arrives’ hook;
- When it happened, we did something—we sent her to the store to get paint; in programming terms we added an action to call the send_gill_to_get_paint() function, which prints a message on the page;
- We used the $gill_has_keys and $gill_has_car arguments to perform some basic logic;
- We set other information:
- The priority of this action: Whether it will run before, or after, other functions attached to the same hook. In this case we set the priority to 10, the default. If we want another function to run before this, we would give the other function a lower value (which means it will be executed first).
- How many arguments (variables) that the function accepts. These arguments are passed from the action hook to our function. In this case, we set this value to 2.
How did it work?
A simple add_action() example
// Add some text after the header add_action( '__after_header' , 'add_promotional_text' ); function add_promotional_text() { // If we're not on the home page, do nothing if ( !is_front_page() ) return; // Echo the html echo "<div>Special offer! June only: Free chocolate for everyone!</div>"; }<br>
do_action ( '__after_header' )
Filters:
When Jack comes by, bragging about how he’s the best, tone down his boasting.
// Cut Jack's boasting add_filter( 'jacks_boast' , 'cut_the_boasting'); function cut_the_boasting($boast) { // Replace "best" with "second-best" $boast = str_replace ( "best" , "second-best" , $boast ); // Append another phrase at the end of his boast $boast = $boast . ' However, Gill can outshine me any day.'; return $boast; }<br>
What did we just do there?
- We looked for a particular thing that we wanted to change—Jack’s boast that he’s the best; in programming terms the ‘jacks_boast’ filter;
- When we found it, we changed it—we changed “best” to “second-best” and we added another phrase on the end; in programming terms, we filtered the output by calling the cut_the_boasting() function, which replaced part of the string and appended another string (the “.” character concatenates two PHP strings);
- We used the $boast argument (in this case a string that says something like “I’m the best!”) as the basis for our changes.
- We returned a string at the end of the function. This is very important. If you don’t return a string in a filter, you might disrupt the functioning of a program (in this case, we would simply silence Jack … which may not be a bad thing).
How did it work?
echo apply_filters('jacks_boast', "I'm the best in the world.");
A simple add_filter() example
// Change url that is linked from logo add_filter( 'tc_logo_link_url', 'change_site_main_link' ); function change_site_main_link() { return 'http://example.com'; }<br>
apply_filters( ‘tc_logo_link_url’, esc_url( home_url( ‘/’ ) ) )
Why use hooks?
- Change almost anything in WordPress—even quite fundamental things—because a lot of WordPress’s core functions use actions and filters;
- Make changes easily: once you’ve understood the concepts, you can make some incredibly complex changes very quickly;
- Change a theme’s behaviour at the source, rather than trying to retro-fit an inappropriate solution with HTML and CSS;
- Make your own changes easy to understand and easier to debug, because your code is reduced to a minimum;
- Enable and disable your changes easily because each piece of code is a small unit in your functions.php;
- Make your changes relatively upgrade-proof because you no longer need to edit or copy WordPress or any themes and plugins core files;
- Share your knowledge and swap code snippets with others.
Try it yourself
- In the add_action() example that echoes text for Gill:
- You will need to include the line do_action( ‘after_gill_arrives’ , $gill_has_keys = true , $gill_has_car = true ); in your code, because this action hook isn’t in Customizr.
- If both $gill_has_keys and $gill_has_car are set to true, then your website will display “Gill, please go to the store and get some paint. Thank you!” at the top of the page. If you change either one or both of these values to false, the message will not display.
- In the add_action() example to add promotional text: Don’t include the ‘__after_header’ hook in your code, because this already included in Customizr’s core code.
- In the add_filter() example that changes Jack’s words:
- You will need to include line echo apply_filters(‘jacks_boast’,”I’m the best in the world.”); in your code, because this filter hook isn’t in Customizr.
- Your website will display “I’m the second-best in the world. However, Gill can outshine me any day.” at the top of the page.
- In the add_filter() example to change the logo url: Don’t include the ‘tc_logo_link_url’ filter hook in your code, because this already included in Customizr’s core code.