Back to Guides

7.7.2 – Hooks

Both WordPress and the Genesis Framework make use of hooks.  A hook is a PHP function that allows other functions to execute at that point in the code. Hooks execute in the order that they appear in the overall WordPress code. There are hooks throughout the Genesis Framework which you can make use of to apply functions at specific sections of your site structure.

We can hook a function to a hook by using the function add_action(). We can execute all the functions hooked on those hooks by using the function do_action(). To remove a function from a hook we use the function remove_action().

In the core Genesis Framework files you will see do_action() functions throughout the code. As an example, in the /genesis/header.php file you will find:

do_action( 'genesis_before_header' );
do_action( 'genesis_header' );
do_action( 'genesis_after_header' );

Using Hooks

There are two functions in WordPress that allow us to make use of these action hooks: the add_action and the remove_action functions. They are presented in the format:

add_action( $hook, $function_to_add );
remove_action( $hook, $function_to_remove );

The add_action and remove_action is the instruction type. The variable $hook identifies the hook we will use. The variable $function_to_add identifies the function we will use. The add_action function causes a specified function to execute at that hook. The remove_action function prevents a specified function executing at that hook. To remove an action find the action you want to remove in the Genesis Framework directory, copy it into your child theme’s functions.php file, and change “add_action” for “remove_action”.

WordPress ignores duplicates of identical add_action and remove_action functions and those that reference invalid hooks or functions. A remove_action() is ignored if the corresponding add_action() isn’t present. The Genesis Framework uses conditional codes for the loop and comment template: if the loop isn’t loaded then the conditional loop hooks don’t load and if the comment template isn’t loaded then none of the comment hooks load.

Multiple add_action statements can reference the same function using different hooks allowing multiple calls of that function without duplicating that function’s code.

You can also move a function from one hook to another. To do this find the add_action function. Copy it to your child theme twice. In the first instance replace ‘add_action’ with ‘remove_action’. This will remove the action from it’s hook. In the second instance change the current hook for the one you want the code to execute at. For example the functions.php file of your child theme the Genesis main navigation can be moved:

We copy this code from the Genesis Framework directory

add_action( 'genesis_after_header', 'genesis_do_nav' );

Then we paste this in our child theme twice. In the first instance we change the add_action for remove_action.

remove_action( 'genesis_after_header', 'genesis_do_nav' );

In the second instance we change the original hook for the new one we want.

add_action( 'genesis_before_header', 'genesis_do_nav' );

The remove_action function prevents the Genesis main navigation function from executing at the ‘genesis_after_header’ hook. The add_action function hooks the Genesis main navigation function to the ‘genesis_before_header’ hook.

Priority

Priority is a number added to the end of an add_action function or remove_action function which determines the order in which the function given in that add_action function or remove_action function is called in relation to other functions using that same hook.

The number 10 is the default priority assigned to all action statements and does not appear in the code. We can assign a number lower or higher than 10 to adjust the order in which the function is called by adding it to the end of the function. Lower numbers are called before higher numbers.

You cannot remove an action before it is added: the add_action has to exist before the remove_action can execute. A remove_action function must therefore have a priority higher than the add_action function it is seeking to prevent executing. For example:

add_action( $hook, $function_to_add, 5 );
remove_action( $hook, $function_to_remove, 15 );

Hooking a Function in a Child Theme

In this example we will create a file for a function that will display a portfolio in a custom loop, say, for the website of an artist.

Create a new file and place it into your child theme folder. Name it. E.g. portfolio-loop.php.

To this file add all your additional functionality, markup and CSS.

Create a function in your functions.php file to call your portfolio-loop.php file:

function include_portfolio_loop() {
require(CHILD_DIR.'/portfolio-loop.php');
}

“function” tells the server this is a function.

“include_portfolio_loop()” is the function name. It is what you call to be executed. It must be unique and, for your own ease of use, it is helpful to name it descriptive of what it does e.g. portfolio_loop for a function which handles a portfolio of images.

“()” is the “argument” for the function and describes the number of variables that can be sent to the function. Functions don’t require an argument, as in this case, but can handle more than one variable.

{} the curly braces contain the code that will be run when the function is executed. In this example that code is “require(CHILD_DIR.’/portfolio-loop.php’);”.

Having defined your function you can add it to a the appropriate hook with an add_action statement:

add_action( 'genesis_entry_content', 'include_portfolio_loop' );

In this example the function include_portfolio_loop() has been hooked to genesis_entry_content. The “add_action” adds the function to the hook, the “genesis_entry_content” is the hook you are adding to, and “include_portfolio_loop” is the name of the function you are adding.

The code in full then:

add_action( 'genesis_entry_content', 'include_portfolio_loop' );
function include_portfolio_loop() {
require(CHILD_DIR.'/portfolio-loop.php');
}

The do_action (genesis_entry_content) which executes this function is found in the framework.php file. It is part of the parent directory so does not need calling in your child theme.

Back to the Top