Using Actions, Filters & Hooks

Child Theming

Last Updated: Time to Read: 7 minutes

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.

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:

Dave going to get cat food would look like this:

How does it work?

  1. 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.
  2. 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.
  3. 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:
  4. 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.
  5. 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.
  6. 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:

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_hungry  to 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 .

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.

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.

See the Layers Hook Reference: Actions for a look at all the action locations in Layers

A layers extension might already hook into layers_after_logo  and add stuff that doesn’t jive with your custom action.

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.

References on the WordPress Codex:

 

When the cat meows, Dave feeds her.

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:

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:

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!”.

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.

See the Layers Hook Reference: Filters for a range of examples

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:

  • Change almost anything in WordPressvia the amazing WordPress API
  • Make changes easily: once you’ve understood the concepts, you can make complex changes very quickly
  • Change Layers’s funcitonality at the source without modifying the core or trying to hack it with an inappropriate solution with HTML and CSS
  • Make your changes reuseable and easy to understand and debug.
  • Enable and disable your changes easily by commenting out single blocks of code in your functions.php
  • Because you no longer need to edit or copy WordPress’s or Layers’s core files, your changes will not be lost when updating;
  • Share your knowledge and swap code snippets with others on the Layers Community

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

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.

Take a look at the following to extend your knowledge further: