AJAX (Asynchronous JavaScript and XML) is one of the handiest features/group of interrelated technologies you can include on your website. With AJAX you enable your page to perform database retrievals and changes without reloading the page. WordPress comes with built in support for using AJAX calls from within your plugins so today I wanted to go through a simple example and create a plugin that uses AJAX calls for demonstration purposes. Hopefully you can take this simple code and expand on it to use AJAX calls in your own plugins.

A few things to note before we get started:

• This tutorial is aimed at those who have a working knowledge of jQuery, I don’t really go into a lot of detail about it
• This tutorial also assumes you know the basics of creating your own WordPress plugin as I don’t go into a lot of detail about that either
• If you want to learn how to use jQuery I have four tutorials on the subject: Part I, Part II, Part III, Part IV
• If you want to learn all the details of creating your own WordPress plugin I have a tutorial on that as well

Our Objective

The objective for this plugin is to be able to perform AJAX calls to retrieve our WordPress Options and display them in a table. It’s a simple example but it shows you exactly how AJAX works within WordPress and it’s a really great base to build off of.

At the end of this tutorial there will be a link to download a full copy of the plugin that you can install in case you don’t want to write the code yourself. If you’re not only too lazy to write the code but also too lazy to scroll to the bottom of the page, you can also download the zip file by clicking here. Be sure to read over the code and then expand on it to create something great.

Enqueuing Our CSS

The first thing we have to do (we don’t actually have to do it in this order at all, but I always do it first) is hook in our CSS. We will just have a little CSS at the end to make everything look nice.

Creating the Admin Page

Creating the admin page requires two functions. One functions will create the menu item and setup the page’s details, while the other is the actual physical content of the page. Creating a new page is as simple as calling add_menu_page( … ) and hooking it in with the admin_menu hook. This way our testing page will appear on the back end (you don’t want it on the front end since it will show all your options!).

If you don’t know about them already, Dashicons allow you to use a set of ready-to-go icons that work great with WordPress as your menu item. In this case I use a clipboard since this is a testing type plugin and it seemed to fit, but there are loads of others to choose from on their site so check it out.

Our next function creates the actual physical look of the page. While it is possible to just exit out of the PHP tags and write straight HTML, I usually like to just add everything to a PHP variable called $html and just echo it at the end of the function. In this case all we need to build is a table to display our results, a text field for the ID of the option we want to get, and a button to activate the AJAX call.

The JavaScript

Our JavaScript/jQuery is pretty short and simple, but there are a few things worth noting. As with almost all AJAX calls no matter where you’re working, we add an event listener to activate the call. In this case we add an event listener to our button. Once the button is pressed the event listener will fire up it’s function which will get the ID of the option from the input field and then pass it to the $.ajax( … ) function in jQuery.

This is where the WordPress specific things happen. Note in the $.ajax( … ) function call our url is set to ajaxurl. Since WordPress 2.8 ajaxurl is always defined in the admin header and points to admin-ajax.php. We will hook our PHP handler function into admin-ajax.php in the next step.

The other WordPress specific thing to note is the action key inside the passed data. This needs to be set and we need to take note of what we call it because we will have to use it as the part of the hook name for our call to add_action( … ) when we create our PHP handler function.

Once the call is made, if it is successful we append the option’s data that is return to the table. This is all pretty standard jQuery stuff, but if you’re having trouble with it I have four tutorials on the basics of using jQuery: Part I, Part II, Part III, Part IV.

PHP AJAX Handler

Finally we need to make our PHP handler function for the AJAX call. This function will perform like any other, so all it really needs to contain is some $wpdb code to get the option with the ID passed to it in order to function.

The only thing of importance to note is the use of add_action( … ). Remember in the previous section that I said we needed to remember the value of the action key inside the passed data. When you call add_action( … ) the hook name should be wp_ajax_ and then whatever the value of the action key was. You can think of it like a required concatenation. In my example my action key was called dobsondev_ajax_tester_approal_action so my hook in the add_action( … ) call has to be wp_ajax_dobsondev_ajax_tester_approal_action in order to work.

Finally make sure you return the data with an echo call followed by a wp_die() call.

Thanks to Tom Cloud for emailing me a change to this code.

The Finished Code

Below you will find the complete plugin code as well as the code for the CSS file. If you want to download a zip of it just click here.

Hopefully the code and this tutorial will help you get well on you way towards creating your own plugins with AJAX calls. Remember that AJAX is not restricted to just the admin side, simply change the hook for the JavaScript add_action( … ) call and it can go anywhere. Also always make sure to remember your action key name so you can use it in the hook for the call to add_action( … ) in your PHP handler function.

As always thank you for reading and please share it around as much as you can! Please feel free to put any suggestions or ideas for future tutorials in the comments section below.