Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

I'm trying to understand where to use filters and where to use actions.

Suppose I have a query in a plugin, which later add on modules might modify to change the results of the query, thus modifying the arguments.

Would this be an ideal implementation of this concept, or should I be using actions here?

// Function to display list of pages

function get_page_list() {
    $pages_args = array(
        'post_type' => 'page',
        'posts_per_page' => '1'
    );  
    $pages_query = new WP_Query( apply_filters( 'myfilter', $pages_args ) );


    if( $pages_query->have_posts() ) {
        while ( $pages_query->have_posts() ) : $pages_query->the_post();  
            echo get_the_title();
        endwhile;
        // Reset Post Data
        wp_reset_postdata();
    } 


    else echo 'no results found';                 

}
add_action( 'wp_footer', 'get_page_list', 1); 


function change_page_to_post( $pages_args ) {
    $pages_args = array(
        'post_type' => 'post',
        'posts_per_page' => '1'
    );  
    return $pages_args;
}
add_filter('myfilter', 'change_page_to_post');
share|improve this question
add comment

3 Answers 3

up vote 2 down vote accepted

+1 to both of the other answers, for explaining the primary differences between actions and filters.

However, to answer your specific question, about which to use for modifying a query:

  1. Injecting your custom query into the template does, as you guessed, require hooking into an existing action. (Whether or not wp_footer is the correct/ideal action is another matter, and would depend on exactly how you intend to use said query.
  2. Allowing your custom query is probably best accomplished using a custom filter, that other Plugins can hook into.

For example, starting with this code:

function get_page_list() {
    $pages_args = array(
        'post_type' => 'page',
        'posts_per_page' => '1'
    );  
    $pages_query = new WP_Query( apply_filters( 'myfilter', $pages_args ) );


    if( $pages_query->have_posts() ) {
        while ( $pages_query->have_posts() ) : $pages_query->the_post();  
            echo get_the_title();
        endwhile;
        // Reset Post Data
        wp_reset_postdata();
    } 


    else echo 'no results found';                 

}
add_action( 'wp_footer', 'get_page_list', 1); 

If you want this code to be extensible, you need to provide a way for others to extend it. I would recommend making your custom query args extensible, via custom filter. e.g. this:

$pages_args = array(
    'post_type' => 'page',
    'posts_per_page' => '1'
);  

...could easily become this:

$pages_args = apply_filters( 
    'custom_filter_name', 
    array(
        'post_type' => 'page',
        'posts_per_page' => '1'
    ) 
);  

Which would then allow other Plugins to modify your query args. For example, if a Plugin wanted to return two posts, instead of one:

function wpse73840_modify_custom_filter_name( $args ) {
    // Modify posts_per_page
    $args['posts_per_page'] = '2';
    // Return modified args
    return $args;
}
add_filter( 'custom_filter_name', 'wpse73840_modify_custom_filter_name' );

I think this gets to what you're asking. If not, let me know in the comments.

share|improve this answer
    
Yes that's exactly the answer I was looking for. Now that I know I was on the right track with using a filter, can you explain why your placement of the filter is better (if it is) than my original code's placement of the filter? I had used $pages_query = new WP_Query( apply_filters( 'myfilter', $pages_args ) ); –  drtanz Nov 24 '12 at 22:41
    
I don't know that one is better than the other; it is more just a matter of preference. I find filtering the $args variable directly is a bit easier to read; but either way should work fine. In fact: I didn't even notice your apply_filters() call, because I never would have thought to look for it directly inside the WP_Query() call. :) –  Chip Bennett Nov 24 '12 at 23:01
    
Ok, all good then, most importantly I know I'm doing things right and I understood the hook concept. Thanks for your help. –  drtanz Nov 24 '12 at 23:03
add comment

The basic difference is that filters are meant to change some value & actions are meant to do some work. They work almost the same way in the code but the difference is that filters have to return a value whereas actions don't.

Let's say your plugin created a new page in the database. After the task is completed, you want to let other people add some custom fields to the new page. For this task, you'll want to send an action. Other plugins will hook into this & add the fields only when the page is created

Now let's say you're going to display some message to the user, but you want that message to be customizable by other plugins. Then you'll apply a filter. Other plugins hooking into the filter will change this message & return it back to you. Now you'll display the new message to the user. Not the one you originally intended.

For this reason filters always return a value whereas the return value of an action is ignored.

Please note that this is not a rule in terms of coding. You may use one or the other as you like & it won't throw any errors but they are different in how they are named & how wordpress intended them to be & it's very highly recommended that you follow this pattern.

share|improve this answer
    
Yes I agree, however in this particular case what would you choose? I am not strictly speaking modifying any content directly, so should I use an action instead of a filter? –  drtanz Nov 24 '12 at 22:03
add comment

My Congratulations. You understand topic perfectly. Filters if you want to change incoming content (that's why its filter). Action thats if want to do something (that's why its action).

share|improve this answer
    
Thanks, however in this case I am still not sure about what I should use, since I am not changing incoming content directly, I'm just modifying a query. Would an action be more suitable? –  drtanz Nov 24 '12 at 22:04
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.