wordpress filters documentation? Trying to understand add_filter()

Question

I read over the documentation several times and have been having a hard time trying to figure out what is going on with the function. I'm more and more confused after looking at the documentation, looking over the source code as well.

add_filter($tag, $hook, $priority, $args);

it seems to me the new function extends the parent function. What puzzle's me is what parts of the hook becomes overridden. in some examples in the documentation i see that some variables are replaced with the $args in your new $tag.

I almost understood it all here: http://www.andrewnacin.com/2010/05/18/rethinking-template-tags-in-plugins/

but then i couldn't figure out how you pass arguments and which eventually get overriden.

thanks in advance.

Answer 1

it is very nice article, but I must do some stupid mistake, nevertheless....

I am trying to remove some items in WP3+ Navigation Menu under "Screen Options" via this "add_filter" technique:

wp-admin/includes/nav-menus.php:

function wp_nav_menu_manage_columns() {
    return array(
        '_title' => __('Show advanced menu properties'),
        'cb' => '<input type="checkbox" />',
        'link-target' => __('Link Target'),
        'css-classes' => __('CSS Classes'),
        'xfn' => __('Link Relationship (XFN)'),
        'description' => __('Description'),
    );
}

mytheme/function.php:

It seems the original functions is not a part of some CLASS:

add_filter('wp_nav_menu_manage_columns', 'new_wp_nav_menu_manage_columns');
function new_wp_nav_menu_manage_columns() {
    return array(
        '_title' => __('Show advanced menu properties'),
        'cb' => '<input type="checkbox" />',
        'link-target' => __('Link Target'),
    );
}

But as a result I can see the original "Screen Options" with all the items. If I remove the lines: 'css-classes' => _('CSS Classes'), 'xfn' => _('Link Relationship (XFN)'), 'description' => __('Description'), directly in WP core, everything looks OK, so I am not sure it it is possible to override all the WP functons this way.

Thank you very much for your advice. With best regards, Milo

Answer 2

Chris, You seem to be confused by a few things:

1. Filters and Actions are not related (they're both a type of what WP calls a 'hook', but otherwise unrelated). Above you said "with my filter..." but do_action() is for Actions not Filters.
2. The Tag (i.e. tag parameter to add_filter, apply_filter, add_action, do_action have nothing to do with tags in the XML/HTML sense (- maybe you know that).
3. When invoking an Action, using do_action() you probably want to pass an argument in addition to the mandatory tag name. Above you called do_action('content_class'), which, firstly, will have no effect unless you've first registered an Action with the tag name "content_class", and secondly, in your action function content_class_filter (which would be better named content_class_action as is has nothing to do with filters), has an optional parameter $classes, which will always be '' since you didn't supply an argument to do_action after the tag name. Note also you probably meant to write $output = ..
4. Filters don't "override" anything (especially in the OO language sense). Adding multiple filters with the same tag will result in all of them being called when the apply_filters for the tag is called. You can control the ordering using the priority parameter. Same goes for Actions.

Answer 3

add_filter() is a companion function to apply_filters(). Before apply_filters is run for a certain filter (the $tag argument in add_filter()), you can use add_filter to register a filter for a tag. When apply_filters() is executed with that tag name, it calls all the registered filters in order. Filters are used to pass data through functions for manipulation. For example, one that I often find myself using is the wp_list_pages filter. I use it to remove line breaks from the pages list. So here's how it works:

First I define a function that takes one parameter and returns it after working with it:

function my_list_pages_filter($pages){
  $pages = preg_replace( array("\n","\r"), '', $pages );
  return $pages;
}

Then I add the filter hook: add_filter( 'wp_list_pages', 'my_list_pages_filter' );

add_filter tells WordPress "When the function apply_filters is called with the first argument being 'wp_list_pages', call my_list_pages_filter." Filters must send at least one value (of any type: string, array, integer, etc.), and they expect the function to return one value.

They provide you a way to manipulate the input before sending it back.

do_action is an entirely different hook. In order to send information to your filter function, do the following (taken from your example):

<div id="content" <?php $class='post post_content'; echo apply_filters('my_custom_classes', $class); ?>>

And then in your functions.php file, add this:

add_filter('my_custom_classes','my_custom_classes_function');
function my_custom_classes_function($classes){
  $output 'class="'. $classes.'"';
  return $output;
}

That's a pretty rudimentary use of filters, but it's a start. You can really get an idea of what you can do with filters with the same example with some enhancements:

function my_custom_classes_function($classes){
  $classes = explode( ' ', $classes );
  if(is_home())
    $classes[] = 'home_content';
  if(is_single())
    $classes[] = 'single_content';
  if(is_page())
    $classes[] = 'page_content';
  if(is_tag())
    $classes[] = 'tag_content';
  $output 'class="'. implode( ' ', $classes ) .'"';
  return $output;
}

Answer 4

i have placed hook here in the template file:

<div id="content" <?php content_class() ?>>

the hook just self executes in the functions file:

function content_class() {
 do_action('content_class');
}

with my filter i'm trying to pass classes to this function.

function content_class_filter($classes='') {
   $output 'classes="'. $classes.'"';
   return $output;
}

then finally i'm really confused as to how to write the filter...