Back to Guides

7.2.1 – Filters

Filters are functions which modify target functions. The filters are hooked into place by add_filter() and applied to the target function by apply_filters(). Only those functions which include apply_filters() in their code can have filters applied to them.

When present in code this is what apply_filters() looks like:

apply_filters( $tag, $value, $var1, $var2, ... );

$tag is the name of the filter being applied.

$value is the value that can be modified.

$var1 and $var2 are variables that can be used to get additional information. The content of a $var can’t be changed but it can be used; in, and not limited to, both str_replace() searches and conditional statements e.g.

if( ‘story’ == $var1 )
return ‘fiction';

Once a function with apply_filters() has been chosen a filter can be added to modify it’s output. This is done by using add_filter().

add_filter( 'example_filter', 'filter_function', 10, 2 );

The function add_filter() has the same layout as the function add_action():

  • ‘add_filter’ is the instruction to add the filter
  • ‘example_filter’ is the filter name to work with
  • ‘filter_function’ is the name of the filter function that will modify the value
  • ’10’ is the priority
  • ‘2’ is the number of arguments that the function will use

In the code below a function is added and defined and a filter is added and defined to modify it:

// Adding the function to a hook
add_action( 'example_hook', 'example_function' );

// Defining the function which includes a filter
function example_function() {
echo apply_filters( 'example_filter', 'Hello', 'var 1', 'var 2', 'var 3' );
}

// Adding the filter
add_filter( 'example_filter', 'filter_function', 10, 2 );

// Defining the filter function: change the value if $var1 == 'var 1'
function filter_function( $value, $var1 ){
if( 'var 1' == $var1 )
return $value;
return 'Ahoj';
}

The add_action() hooks the example_function() to the example_hook. The example_function() echoes ‘Hello’ to the screen. The apply_filters() applies the filter to modify the example_function(). In order to be applied the filter must be added and defined otherwise it will have no effect. The add_filter() adds the filter for example_function().

The arguments in the functions begin with the $value and proceed to the $var. Each $var in an argument must have a value, even if that $var is not being used: if $var2 was required $var1 would still need a value. In the code above the filter_function() has been defined with two arguments: the $value and $var1.

The filter_function() checks if $var1 matches the specific string ‘var 1’. In this case it will as ‘var 1’ is static, however there are occasions when functions might have dynamic values returning different values in different scenarios. Having checked that $var1 matches ‘var 1’ the filter_function() then returns the $value and returns ‘Ahoj’. ‘Ahoj’ will be printed on the screen and replaces the example_function() $value ‘Hello’.

The final $value must always be returned, not echoed, so other filters can use it if need be. It is returned first as $value rather than ‘Ahoj’ so other filters can use $value rather than ‘Ahoj’.

Removing the Filter

The remove_filter() function is identical in use to the remove_action() function. It must match the add_filter() exactly and has to appear in the code after the filter has been added.

Using Filters with Strings

Replacing a String Value

We can use filters to replace a string with a different value. The example below shows how the text for a search which returns no results can be changed. As a default the text “Sorry, no posts matched your criteria.” is returned. The custom value which will replace it will be the text “We do apologise, no posts were found for your search.” The code for this is found in post.php:

genesis_do_noposts
add_action( 'genesis_loop_else', 'genesis_do_noposts' );
function genesis_do_noposts() {

  printf( '<div class="entry"><p>%s</p></div>', apply_filters( 'genesis_noposts_text', __( 'Sorry, no content matched your criteria.', 'genesis' ) ) );

}

// Add the filter to change the value 
add_filter( 'genesis_noposts_text', 'search_noposts_text' );

// Define the function to change the No Posts text for search pages
function search_noposts_text( $text ) {
if( ! is_search() )

// The $text is returned so other functions can use the original value.
return $text;

// The custom value is returned and will display on search pages which don't return any results.
return '<span class="no-posts">' . __( 'We do apologise, no posts were found for your search.', 'genesis' ) . '</span>';
}

Sidenote: The __() function is used for translating the text.

Changing a String Value

Sometimes it is more useful to change just some of a string. To demonstrate how to do this the example below uses str_replace() to use a custom string along with the values of $backtotop_text and $creds-text. At the end of the genesis_do_footer() function, you will find:

footer credits filter

Now to modify it:

// What we find on line 160 of footer.php
echo apply_filters( 'genesis_footer_output', $output, $backtotop_text, $creds_text );

// Adding the filter to change the string
add_filter( 'genesis_footer_output', 'modify_footer_text', 10, 3);

// Defining the function which modifies the footer text
function modify_footer_text( $output, $backtotop_text, $creds_text ){

// Custom string with Copyright, a start date and the current year as the end date and the website title
$modified_footer_creds = 'Copyright 2014 - '. date( 'Y' ) .'<a href="http://genesistutorials101.com/">Genesis Tutorials 101</a>';

// Using  str_replace() to find the $creds_text inside the $output and replace it with the custom $modified_footer_creds
$output = str_replace( $creds_text, $modified_footer_creds, $output );
return $output;
}

Using Filters with Arrays

An array is an ordered group of strings, an efficient way of storing related information without needing to have many separate variables. There are two parts to an array, first the key and then the value. They can be assigned a number of ways which will effect how they appear in the code. Arrays can contain strings (first four examples) or nested arrays (last example):

// Keys listed as 'key1' with a string value of 'value1' and 'key2' with a string value of 'value2'
$array_1 = array( 'key1' => 'value1', 'key2' => 'value2');

// Keys not manually listed so automatically assigned a key value of 0 and 1  
$array_2 = array( 'value1', 'value2' );

// Added to the existing $array_2 string above this key would have a key value of 2
$array_2[] = 'value3';

// Added to the existing $array_2 string above here the key of '3' is manually assigned the value of 'value4'
$array_2['3'] = 'value4';
// Nested array: $array_3 is made of two object arrays, an 'odd' number array and an 'even' number array
$array_3 = array( 'odd' => array( 1, 3, 5 ), 'even' => array( 2, 4, 6 ) );

Using a Filter to Add to an Array

Arguments can be added to arrays. As an example the argument ‘label_submit’ can be added to the list of arguments in the comment form. This could be accomplished by unhooking the action and adding a new action with a new function that has all the original code plus the label_submit value. A simpler way to accomplish this is to use a filter: comment form args

// Add the filter
add_filter( 'genesis_comment_form_args', 'modify_comment_form_args' );

// Define the function
function modify_comment_form_args( $args ) {

// Add the label_submit key to the $args array with a value of 'Publish Your Comment'
$args['label_submit'] = 'Publish Your Comment';

//Return the object to be used in the comment_form() function
return $args;
}

Using a Filter to Replace Array Values

The example shown below works with the breadcrumbs arguments found in breadcrumb.php. Notice that line 95 includes ‘apply_filters()’ which means we can apply a filter to the values $args and $this->args. On line 43 you will see $this->args which is what we will change.

breadcrumb.php args
// Add the filter
add_filter( 'genesis_breadcrumb_args', 'modify_breadcrumb_args' );

// Define the function
function modify_breadcrumb_args( $args ) {

// Change ' / ' to '| '
$args['sep'] = ' | ';
// Change 'You are here: ' to 'Your location: '
$args['labels']['prefix'] = 'Your location: ';
// Change 'Archives for' to 'Category: '
$args['labels']['category'] = 'Category: ';

return $args;
}

Provide the same key to change the value.

For nested values like the ‘labels’ object you need to provide the key of the object (‘label’) then the key of the string (‘prefix’ and ‘category’).

Return the array when you are done with it.

Using a Filter to Change an Array

A string replace can be used to change part of a value. For this example we will be removing some invalid markup: the aria-require attribute in the comment form. It is found in the genesis/lib/structure/comments.php file.

change array comments
// Add the filter
add_filter( 'genesis_comment_form_args', 'remove_aria_required_comment' );

// Define the function
function remove_aria_required_comment( $args ){

// Change the value: any string in the $args array has the value 'aria-required = ”true”' replaced with an empty space
$args = str_replace( ' aria-required = "true"', '', $args );

// Change the value: any string in the 'fields' object has the value 'aria-required = ”true”' replaced with an empty space
$args[fields] = str_replace( 'aria-required="true"', '', $args[fields] );

// Return the value
return $args;
}
Back to the Top