AJAX-ifying WordPress Widgets

I recently found the need to give AJAX abilities to a WordPress widget. Notably, I had a request from Kjell Martin Bovre of Scribo.no to allow ThinkTwit to update when used with a caching engine, for instance WP Super Cache. Caching engines work by converting the pages of a site in to HTML and, rather than loading the website code using calls to its database, calling these pages directly when a user makes a request.

The first time that a user visits a site with a caching engine the pages they visit will be converted to HTML. After a period of time these pages will get updated, but if you have a particular item on that page that should be updated more often this will not happen. One way to ensure this item is updated correctly is to enable it to use AJAX. The AJAX code will get called whenever the site is loaded, even in its HTML format – therefore it will work even when cached as the Javascript will make a server call, the server will respond with the up-to-date data and the Javascript will then update the HTML within that page.

After a good few hours research I was able to find a site that helped me do most of this, but there were some errors and it did not work with WordPress widgets as it would break their ability to create multiple instantiations. It was therefore necessary to update the code to allow this, so I thought I would just write a quick and easy guide to writing AJAX capable widgets to allow other developers to quickly and easily resolve this issue. I hope it comes in handy!

1. In your widget constructor e.g. public function myWidget(), enqueue jquery:

   // Load jQuery
   wp_enqueue_script('jquery');

2. In your widget declaration i.e. public function widget($args, $instance), and after extract($args); (if it exists) get the widget id:

   // Get the div id of the widget
   $widgetid = $args['widget_id'];

3. Create a variable to store an option that allows your users to turn on or off AJAX within the widget. Do this in the same function:

   $useAjax = isset($instance['useAjax']) ? $instance['useAjax'] : false;

4. Next you should ensure that the code that outputs the main body of your widget is contained within one function. It may be that you split your code in to many functions, but for simplicity you should call each of those functions from one function that returns your output e.g.

   function mainFunction($parameter1, $parameter2, $parameter3) {
       $output = firstFunctionCall($parameter1, $parameter2);
       $output .= secondFunctionCall($parameter3);
   
       return $output;
   }
   

5. Still in the widget function, and after your widget’s title (“echo $before_title . $title . $after_title;“) enter the following code (this is further explained below):

   // If the user selected to use AJAX then output AJAX method
   if ($useAjax) { ?>
       <script type="text/javascript">
           jQuery(document).ready(function($){
               $.ajax({
                   type : "GET",
                   url : "index.php",
                   data : { mywidget_request      : "some_action",
                               mywidget_parameter1 : "<?php echo $parameter1; ?>",
                               mywidget_parameter2 : "<?php echo $parameter2; ?>",
                               mywidget_parameter3 : "<?php echo $parameter3; ?>"},
                   success : function(response) {
                       // The server has finished executing PHP and has returned something,
                       // so display it!
                       $("#<?php echo $widgetid; ?>").append(response);
                   }
               });
           });
       </script>
   <?php
   // Otherwise output HTML method
   } else {
       echo mainFunction($parameter1, $parameter2, $parameter3);
   }
   

   So the key parts to this code are:

   • The if statement checks to see if the (admin) user has specific that the widget should use AJAX
   • If the user wishes to use AJAX it will output some Javascript.
     1. The first two lines tells jQuery to create a function.
     2. The third line (type) tells the function to use a GET request.
     3. The fourth (url) tells it to use the index.php address (it could technically be almost any page as they should all have access to our method).
     4. The fifth line (data) specifies the parameter that will help us find our request.
     5. The sixth, seventh and eighth lines pass our parameters across the AJAX call.
     6. And finally the ninth, tenth and eleventh tell our Javascript what to do when the request has been returned – that is to append the returned data to the widget with the id that we dug out previously.
   • The else, from the if statement, then tells WordPress to simply output the returned data from the function as the user has decided not to use AJAX.
6. In the update function i.e. public function update($new_instance, $old_instance), add in some code to save your new “useAjax” setting:

   $instance['useAjax'] = (strip_tags($new_instance['useAjax']) == "Yes" ? true : false);

7. In your form function i.e. public function form($instance), add in a default value to your “defaults” array (if it exists) to set a default value for “useAjax”:

   $defaults = array('title'      => 'My title',
                                   'first'      => 'somevalue',
                                   'second'  => 'somevalue',
                                   'third'     => 'somevalue',
                                   'useAjax' => false);
   

8. In the same function add some code to add a drop-down box with yes and no options, to allow the user to enable/disable the useAjax setting:

   <p><label for="<?php echo $this->get_field_id('useAjax'); ?>">
        <select id="get_field_id('useAjax'); ?>" name="get_field_name('useAjax'); ?>" class="widefat">
               <option <?php if ($instance['useAjax'] == true) echo 'selected="selected"'; ?>>Yes
               <option <?php if ($instance['useAjax'] == false) echo 'selected="selected"'; ?>>No
           </select></label></p>

9. Outside of the widget class declaration i.e.

   class ThinkTwit extends WP_Widget {
       // Constructor
       public function myWidget() {
           ...
       }
   }
   
   // Here
   

   Create a new function that will handle your AJAX request on the server side:

   // Function for handling AJAX requests
   function mywidget_request_handler() {
       // Check that all parameters have been passed
       if ((isset($_GET['mywidget_request']) && ($_GET['mywidget_request'] == 'some_action')) && 
         isset($_GET['mywidget_parameter1']) && isset($_GET['mywidget_parameter2']) && 
         isset($_GET['mywidget_parameter3'])) {
   
           // Output the response from your call and exit
           echo mainFunction(strip_tags($_GET['mywidget_parameter1']), 
             strip_tags($_GET['mywidget_parameter2']), 
             strip_tags($_GET['mywidget_parameter3']));
           exit();
       } elseif (isset($_GET['mywidget_request']) && ($_GET['mywidget_request'] == 'some_action')) {
           // Otherwise display an error and exit the call
           echo "Error: Unable to display request.";
           exit();
       }
   }

10. Finally we add the handler to WordPress’ init() function to ensure that it’s included at the top of the page (although not visible) when WordPress is loaded:

    // Add the handler to init()
    add_action('init', 'mywidget_request_handler');

NOTE: One final note to be made is that for the widget to be displayed it relies on the theme it’s running in to be written correctly to display widgets in the dynamic sidebar. This means that each instance of the widget should have an id. To do this it should have code in the functions.php file (or somewhere that is called by this file) along the lines of:

if ( function_exists('register_sidebar') ) {
    register_sidebar(array(
        'before_widget' => '<li id="%1$s" class="widget %2$s">',
        'after_widget' => '</li>',
        'before_title' => '<h2 class="widgettitle">',
        'after_title' => '</h2>',
    ));
}

where the key part here is id="%1$s" in 'before_widget'.

I know that was quite a long procedure but it should give you everything you need to convert your WordPress Widget to one that can use AJAX. To assist, I have built a working example which you may download and use as you wish. If you have any questions please feel free to ask below.

Many thanks to Thaya Kareeson of omninoggin.com for his article Make Any Plugin Work with WP Super Cache.