Apply filters with multiple filters

Question

I'm learning hooks and filters recently; I understand the basics and, using a test wordpress installation and an interesting plugin (for volunteer signup sheets), I have gotten several "add filters" to work properly in the functions.php of a child theme.

Now I am trying to change the wording of some of the headers generated by the plugin, but just can't understand the plugin code so that I can setup the proper "add filter". Hoping someone could give me a short explanation of what is going on here:

$return .= apply_filters( 'pta_sus_before_user_signups_list_headers', '' );
            $return .= '<h3 class="pta-sus user-heading">'.apply_filters( 'pta_sus_public_output', __('You have signed up for the following', 'pta_volunteer_sus'), 'user_signups_list_headers_h3' ).'</h3>';
            $return .= '<h4 class="pta-sus user-heading">'.apply_filters( 'pta_sus_public_output', __('Click on Clear to remove yourself from a signup.', 'pta_volunteer_sus'), 'user_signups_list_headers_h4' ).'</h4>';
            $return .= apply_filters( 'pta_sus_before_user_signups_list_table', '' );

The goal is to change the words "Click on Clear..." to something else. I've tried many different versions of add_filter(), but nothing happens or sometimes the wordpress installation stops working until I remove the offending code from the child functions.php.

Thanks for any help in advance.

Zimbu

Update:

I just dug up some random info on the internet from the plugin author where he/she explains roughly what is going on here:

"You can scan the code in the class-pta_sus_public.php file to see those filters that have the filter hook ‘pta_sus_public_output’, with 2 variables pass to the filter: the first being the original text string, and the second being an identifier key string to let you know which specific text string is being output (so you only modify the one you want to change)."

Now I just have to figure out what that means!

Update2:

Figured it out from something written in the support forum for the plugin. To add a filter to the h4 element, i.e. to change the text that gets displayed in the h4 text section, I added the following to the child functions.php file:

add_filter( 'pta_sus_public_output', 'function_to_change_user_signups_list_headers_h4');
  function function_to_change_user_signups_list_headers_h4( $text ) {
      $text = str_replace(
          array( 'Click on Clear to remove yourself from a signup.' ),
          array( 'Sorry you can not clear' ),
          $text
       );
       return $text;
}

Answer 1

The way apply_filters() works is that the developer provides a name for the filter, and the value that can be filtered. This lets other code modify that value by adding a filter.

In addition the value, however, apply_filters() can also pass additional values to hooked functions so that they can be used inside the filter callback. These are passed as additional arguments to apply_filters():

$value = apply_filters( 'my_filter_name', 'abc', 'arg1', 'arg2' );

In that example, developers who are filtering 'abc' can also access 'arg1' and 'arg2' in their code. This can be useful for passing on additional information about the context, or raw data that was used to create the original value, so that the other developer can re-use it.

An example in WordPress is the the_title filter. This filter also passes along the post ID so that the filter callback can know the ID of the post whose title is being filtered:

apply_filters( 'the_title', $title, $id );

In your example, the same filter is applied to two separate values, but each instance passes along a unique 2nd value that can be used to differentiate between the two.

So if we just look at the filter:

apply_filters( 'pta_sus_public_output', __('You have signed up for the following', 'pta_volunteer_sus'), 'user_signups_list_headers_h3' )

There are 3 parts:

• pta_sus_public_output The name of the filter.
• __('You have signed up for the following', 'pta_volunteer_sus'), the value that you can filter.
• user_signups_list_headers_h3 An additional value that can be used in the filter callback.

In the second filter the last argument is different:

apply_filters( 'pta_sus_public_output', __('Click on Clear to remove yourself from a signup.', 'pta_volunteer_sus'), 'user_signups_list_headers_h4' )

In that case it's user_signups_list_headers_h4.

So by checking this second value, you can apply the filter to only one of the filter instances.

To do this you need to specify that you accept 2 arguments in your callback function:

add_filter( 'pta_sus_public_output', 'function_to_change_user_signups_list_headers_h4', 10, 2 );

That's the last number there. This is the $accepted_args property. The number before that is the priority, and 10 is the default value.

Then inside your function_to_change_user_signups_list_headers_h4() function, accept the additional argument with whatever variable name you want. I'll use $context:

function function_to_change_user_signups_list_headers_h4( $text, $context ) {

The value of $context will now be either user_signups_list_headers_h3 or user_signups_list_headers_h4 (or possibly other values, if the filter is used elsewhere in the plugin), and we can use this to only apply your filter to only the one you want:

function function_to_change_user_signups_list_headers_h4( $text, $context ) {
    if ( 'user_signups_list_headers_h4' === $context ) {
        $text = 'Sorry you can not clear';
    }

    return $text;
}