wordpress filters documentation? Trying to understand add_filter()

4 comments

1. 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;
   }
   

   Log in to Reply

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.

   Log in to Reply

3. 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

   Log in to Reply

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…

   Log in to Reply