jQuery and Ajax in WordPress Plugins – Administration Pages

This is a quick overview of how to use jQuery and its Ajax functions in WordPress. To get the point across, I’ll use a simple and contrived example. We’ll have an admin screen with a list of categories. Clicking on the name of one of the categories will fetch a list of titles of posts in that category and display them as a sub-list of that category.

Step 1: Build the Admin Page

Zipping right by the details of how to add an admin page, here’s the code for adding our category list as a management page.

In category-list.php:

?php
/*
Plugin Name: Category List
Description: A list of categories.
Author: Jonathan Brinley
Author URI: http://xplus3.net/
*/
function category_list_add_management_page(  ) {
  if ( function_exists('add_management_page') ) {
    $page = add_management_page( 'Category List', 'Category List', 'manage_categories', 'category_list', 'category_list_admin' );
  }
}
 
function category_list_admin(  ) {
  $categories = get_categories( 'orderby=name&hierarchical=0&hide_empty=0' );
  include_once('category_list_view.php');
}
 
add_action('admin_menu', 'category_list_add_management_page');

In category-list-view.php:

<div class="wrap">
  <h2>Category List</h2>
  <ul id="category_list">
  < ?php foreach ( $categories as $cat ): ?>
    <li id="cat-<?php echo $cat->cat_ID; ?>" class="category-name"><a href="#">< ?php echo $cat->cat_name; ?></a></li>
  < ?php endforeach; ?>
  </ul>
</div>

Step 2: Add the Ajax Response

As mentioned above, clicking on a category will fetch a list of post titles. So we need a function that builds that list. We’ll add this function to category_list.php:

function category_list_posts(  ) {
  $catID = isset($_POST['catID'])?$_POST['catID']:null;
  if ( $catID ) {
    $posts = get_posts( "numberposts=-1&post_status=publish,pending,future,private,draft&category=$catID" );
    include_once('posts_list_view.php');
  }
  die;
}

And, of course, we need posts_list_view.php:

<ul class="posts_list">
< ?php foreach ( $posts as $post ): ?>
  <li class="post-name post-<?php echo $post->ID; ?>">< ?php echo $post->post_title; ?></li>
< ?php endforeach; ?>
</ul>

We also need to tell WordPress when to call this function, using another action hook:

add_action('wp_ajax_category_list_posts', 'category_list_posts' );

Whenever you post a request to wp-admin/admin-ajax.php with the action parameter of category_list_posts (this being everything after “wp_ajax_” in the action hook), WordPress will call category_list_posts(), the function named in the second parameter of add_action.

Note the call to die at the end of category_list_posts(). When responding to Ajax requests, WordPress will end the response by calling die('0'). If you don’t want that “0” to appear at the end of your response, you have to call die before WordPress gets a chance.

Step 3: Write Your JavaScript

You have your list of categories, and your function that will return the list of posts in a category. Now you need some JavaScript to put them together.

Remember that the Ajax request needs to be sent to wp-admin/admin-ajax.php. Without knowing what directory your plugin will be installed in, nor the full path to wp-admin, you need to provide the URL to your JavaScript somehow. The easiest way I see it to change the href attribute of your links to that URL. So in category_list_view.php, well replace the opening anchor tag with:

<a href="<?php bloginfo('wpurl'); ?>/wp-admin/admin-ajax.php"></a>

With that, we can create a simple JavaScript file (we’ll call it category_list.js):

jQuery(document).ready( function($) {
  $("li.category-name a").click( function() {
    var li = $(this).parent();
 
    /* only fetch results once */
 
    $(this).unbind('click').bind('click', function(){return false;});
 
    $.post($(this).attr("href"), {
        action: "category_list_posts",
        catID: li.attr("id").substr(4)
      }, function(data) {
        li.append($(data));
      }
    );
    return false;
  });
});

This posts data to the given URL, and appends the response to the end of the li.

Now we just need to tell WordPress to include the JavaScript when we’re on the Category List page. Back up in category_list_add_management_page, we’ll make use of that $page variable we set up earlier. Add a line after that:

add_action("admin_print_scripts-$page", 'category_list_scripts');

And add the category_list_scripts function to specify which scripts to add:

function category_list_scripts(  ) {
  wp_enqueue_script( "category-list", path_join(WP_PLUGIN_URL, basename( dirname( __FILE__ ) )."/category_list.js"), array( 'jquery' ) );
}

This plugin doesn’t really do anything useful, but if you want to see the full source code, you’re welcome to download it.