Skip to content

How to Use Hooks

Jump to bottom
Jim Reevior edited this page Aug 14, 2018 · 1 revision

How to Use Hooks

Responsive Framework 2.0 contains some major changes to how child themes override templates and other elements. There are now many new hooks that allow things to be inserted or changed.

Defining Hooks

Hooks are a part of the WordPress core Plugins API. There are two types of hooks:

  • Actions
  • Filters

Benefits of Using Hooks

In Responsive Framework 1.0, it was nearly impossible to change code found in template files. While this is a valid approach, it does have several downfalls.

  1. It prevents the child theme from receiving bug fixes, enhancements, security fixes, etc. that are deployed in Responsive Framework. As soon as the template is overridden, the connection to the parent theme's version of the template file is severed.
  2. It makes it harder to deploy changes to the framework because every child theme that overrides templates with changes needs to be checked for the issue that was fixed in the parent theme.
  3. It needlessly increases the size of our code bases.

An example: say there is an accessibility bug in the single.php template file in Responsive Framework. Child themes that also have a single.php template need to be examined separately for the same bug. If 5, 10, 20+ child themes have this template file, it creates a lot more work.

Action Hooks

Action hooks are used to do something when they are triggered. For an example, let's look at header.php. All action hooks will contain inline documentation stating when the action fires, and explaining any arguments that are available to the hooked functions, if any.

</head>
<body id="top" <?php body_class(); ?>>
	<?php
		/**
		 * Fires immediately after the opening body tag.
		 *
		 * @since 2.0.0
		 */
		do_action( 'r_after_opening_body_tag' );
	?>

Anytime you see do_action( 'action_name' ), WordPress will execute any function that has been attached to the specified action name. In this scenario, the action name is r_after_opening_body_tag.

Adding Functions to Action Hooks

Adding a function to an action hook requires one line of code.

add_action( 'r_after_opening_body_tag', 'mytheme_function_name' );

In the above example, the mytheme_function_name() function will be called in the above do_action() call.

What To Use This For

Action hooks can be used to add markup or elements to a page without having to override the entire template.

Example: Say you need to add markup immediately after the opening body tag, let's say a custom top nav bar.

/**
 * Displays the top-nav-bar.php template.
 */
function mytheme_load_custom_top_nav_bar() {
	get_template_part( 'top-nav-bar' );
}
add_action( 'r_after_opening_body_tag', 'mytheme_load_custom_top_nav_bar' );

The function will load the top-nav-bar.php template, and could be called directly in header.php. But that would require that the file be overridden in the child theme. Action hooks allow code to be executed without overriding template files.

Filter Hooks

Filter hooks are used to change something when they are triggered. All filter hooks will contain inline documentation stating what is being filtered, and explaining all arguments passed to hooked functions. For an example, let's look at header.php.

<main role="main" <?php r_container_outer_class(); ?>>

This line outputs a <main> tag, and calls the r_container_outer_class() function to output the class attribute. By default, this will output class="content". But what if there are additional classes that should be added to this tag? Let's look in the r_container_outer_class() function.

/**
 * Filters the list of CSS classes for the outer content container.
 *
 * @since 2.0.0
 *
 * @param array $classes Outer content container classes.
 * @param array $class   Additional classes added to the outer content container.
 */
$classes = apply_filters( 'r_container_outer_class', $classes, $class );

Anytime you see apply_filters( 'filter_name', $data ), WordPress will execute any function that has been attached to the specified filter name. In this scenario, the filter name is r_container_outer_class.

Adding Functions to Filter Hooks

Adding a function to a filter hook requires one line of code.

add_action( 'r_container_outer_class', 'mytheme_function_name' );

In the above example, the mytheme_function_name() function will be called in the above apply_filters() call.

Note: Filters always pass at least one argument, and a function attached to the filter hook MUST return a value. Filters sometimes pass more than one argument to help provide context to the hooked functions.

What To Use This For

Filter hooks can be used to change or override something that is passed by the filter.

Example: Say you need to add additional classes to the <main> tag above.

/**
 * Adds a class to the outer container tag.
 *
 * @param array $classes Outer content container classes.
 *
 * @return array $classes Adjusted outer content container classes.
 */
function mytheme_add_outer_container_class( $classes ) {
	$classes[] = 'my-custom-class';

	return $classes;
}
add_filter( 'r_container_outer_class', 'mytheme_add_outer_container_class' );

The function will add the my-custom-class class to the list of classes for the outer content container tag.

If your function needs to use the second argument passed to the filter hook, then the code example would become this:

/**
 * Adds a class to the outer container tag.
 *
 * @param array $classes Outer content container classes.
 * @param array $class   Additional classes passed to the outer content container.
 *
 * @return array $classes Adjusted outer content container classes.
 */
function mytheme_add_outer_container_class( $classes ) {
	$classes[] = 'my-custom-class';

	return $classes;
}
add_filter( 'r_container_outer_class', 'mytheme_add_outer_container_class', 10, 2 );

Note the two additional parameters to the add_filter() function.

Welcome to Responsive!

Get started

Configuration

Build child themes

Sass

Javascript

PHP

Shortcodes

Templates

GitHub

Tasks

Contribute to the framework

Code Examples

BU Developer Resources

Clone this wiki locally