Using Actions, Filters & Hooks

Introduction

Hooks are shortcuts that allow you to “hang” your own code on the original functionality of WordPress or any theme or plugin. Hooks come in two forms, Filters and Actions.

Actions do stuff

Filters change stuff

Hooks provide you a means of building a child theme without needing to include copies of original Layers files. This greatly reduces the amount of time you spend on future maintenance, support and troubleshooting of issues that may arise as Layers evolves and gets updated.

Hooks are a great way to assess whether the changes you want to make with a child theme will work well with Layers extensions and future functionality. For example, you can’t change an H1 into an H2 with a hook – it requires rewriting the markup in the templates. This is a good indication that it isn’t a good idea. See our Best Practices guide for more detail on when you should dive into template modification.

Context

When Dave is done with work, he must go to the store to get cat food. When the cat meows, Dave feeds her.

More than a candid look into our CEO’s daily life, this line helps us understand the context, subject, object and order of what our hooks need to establish.

Let’s take a look at how to achieve this with actions, filters and hooks.

Actions

When Dave is done with work, he must go to the store to get cat food.

We can do this by hooking onto an Action. WordPress provides us with the add_action function, which allows us to hook a provided action and tell it what to do.

In a nutshell, the syntax looks like this:

PHP

1

add_action($hook,$function_to_add,$priority,$accepted_args);

Dave going to get cat food would look like this:

PHP

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

// Let's get the cat some food!

//This enables Dave to go to the store after work

add_action('after_work','get_cat_food',10,2);

//This defines how does it

functionget_cat_food($dave_has_wallet,$cat_is_hungry){

// Dave only goes if he has the cash and the cat needs food

if($dave_has_wallet&&$cat_is_hungry){

echo'Dave is on his way to the store';

}

}

How does it work?

We created an action for Dave that defines when he goes to the store( the after_work hook ) and what to do when after_work happens (the get_cat_food funtion). We can reuse the after_work hook for other actions too, such as drive_home or feed_cat.

We set a priority for this action to 10 (default) to ensure get_cat_food happens before drive_home, which we might set to a priority of 20.

The final digit in the action refers to how many arguments the action will take. The default is 1 and in most cases you don’t even need to define this. In our get_cat_food function, we have two of these so we should set this number to 2:

PHP

1

($dave_has_wallet,$cat_is_hungry)

We created the get_cat_food function to house the stuff that getting cat food involves. The function is what contains the code that will be executed when after_work happens, and can be as simple as basic HTML, or contain arguments to help refine the conditions or settings for this action.

In our function get_cat_food, two variables are set to help determine whether this action should happen: $dave_has_wallet and $cat_is_hungry. These will be defined in the template where the output should appear, represented by our hook after_work.

Next, we performed a basic check to see if these variables are true.

Putting the action into action:

On its own, defining an action does nothing unless the hook exists somewhere.

add_action() tells WordPress to do something when it arrives at the specified do_action() hook

An example of using do_action() with our custom action would look like this:

PHP

1

do_action('after_work',$dave_has_wallet=true,$cat_is_hungry=true);

This tells WordPress to create a hook called after_work , run any actions that are attached to this hook, and pass the arguments for$dave_has_wallet and $cate_is_hungryto those actions (the 2 arguments we specified above).

In a hook where you have no arguments, this might be as simple as do_action('after_work'); which will run all the actions that use the after_work hook in he order of priority, including drive_home and feed_cat .

Example of Action Hooking

Layers establishes several hooks throughout the templates which allow you to do stuff before or after a line or group of code, so you would only need to create custom hooks for use in custom templates, if necessary. In this example, we will use the layers_after_logo hook to place a row of social icons after the logo. This code would go into our child theme’s functions.php.

PHP

1

2

3

4

5

6

7

add_action('layers_after_logo','my_header_social_links');

functionmy_header_social_links(){

/* do stuff */

}

That is all you need to do. The layers_after_logo hook is already set by do_action on the last line of the partials/header-logo.php template. By creating an action that hooks onto layers_after_logo , you don’t need to copy the entire template into your child theme just to add your custom HTML after the logo’s HTML.

Overriding plugins

You can use remove_action() to remove that action from the hook, but this requires you to know what the action is either by digging into the extension code or asking the developer. This also raises the risk that your users will complain that your theme breaks a plugin they want to use, so use with discretion and only when absolutely necessary.

remove_action() is particularly useful in cases where a plugin has created an unsavory action that uses a core WordPress hook that you need to remove and override.

Filters

We can change what the cat does by hooking onto a filter. That is, we can use add_filter() to modify the behavior or functionality (ie change stuff) at a given point.

Giving the cat the gift of speech would look like this:

PHP

1

2

3

4

5

6

7

8

9

10

11

// Cast Animal Whisperer V on Dave

add_filter('cat_meows','cat_can_speak');

functioncat_can_speak($meow){

$meow="I'm hungry now.";

return$meow;

}

How does it work?

We looked for a particular thing that we wanted to change

When we found it, we changed it

We used the $meow argument (in this case a string that said “meow!” originally)

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 the hook and trigger a fatal error.

In simple terms, add_filter() tells WordPress to swap its data with ours when it arrives at the cat_meows filter hook.

But we can only use our add_filter() filter in the example above if we know that the cat_meows filter hook exists. (This is why the filter reference exists!)

Behind the scenes, our theme’s original filter might look like this:

PHP

1

echoapply_filters('cat_meows',"meow!");

This tells WordPress to create a hook called ‘cat_meows’, apply any filters that are attached to this hook, and pass those filters along with the string “meow!”. If there are no filters attached to the hook, then the apply_filters() function will simply return the string “meow!”.

Example of Filtering

Filters are useful when creating a child theme or extension for Layers in that you can change the output of programmed elements such as customizer controls, image sizes or pagination, to name a few.

Why use hooks?

Now you know how they work, you can see that understanding hooks is absolutely necessary for anyone developing with WordPress. It’s also very useful even if you are not a developer but want to modify WordPress’s—or your theme’s— behaviour. With an understanding of hooks, you can:

Fully understanding hooks can take a few hours or (much) longer, depending on your skills, but it will save you days of time in the future.

Install our Simply Show Hooks plugin for an easy way to view hook locations in Layers Download

Recommended Reading

Take a look at Layers’s code to see where there are do_action() and apply_filters() functions. If you copy the theme to your hard disk, you can search using your favorite desktop search tool. It will give you an idea of the variety of things you can customize.