A few years ago, I wrote a series of posts discussing how to use Ajax in the WordPress Frontend. The purpose of the series is simple:

We're going to give a very brief overview of what Ajax is, how it works, how to set it up on the front, and understanding the hooks that WordPress provides. We'll also actually build a small project that puts the theory into practice. We'll walk through the source code and we'll also make sure it's available on GitHub, as well.

Generally speaking, the series holds up well but, as with all software under constant development, techniques, APIs, and approaches change. Furthermore, as years pass and we continue to refine our skills, we get better at development and we get better at employing new APIs.

Because of all of the above, I want to revisit the concept of Ajax in WordPress so you see some of the new APIs and how to employ them in your day-to-day work or how to refactor some of the code you may be working with right now.

A word of caution before you go too far into this tutorial: I assume that you have already read through the series linked in the introduction of this article, and that you have some experience with building WordPress plugins.

Defining the Plugin

As with any WordPress plugin, it's important to make sure you define the header so WordPress will be able to read the file in order to introduce the new functionality into the core application.

I'm calling this variation of the plugin Simple Ajax Demo, and it's located in wp-content/plugin/wp-simple-ajax. The first file I'm creating resides in the root directory of wp-simple-ajax and is called wp-simple-ajax.php.

It looks like this:

<?php

/**
 * Plugin Name:       Simple Ajax Demo
 * Description:       A simple demonstration of the WordPress Ajax APIs.
 * Version:           1.0.0
 * Author:            Tom McFarlin
 * Author URI:        https://tommcfarlin.com/
 * License:           GPL-2.0+
 * License URI:       http://www.gnu.org/licenses/gpl-2.0.txt
 */

The code should be self-explanatory, especially if you're used to working with WordPress Plugins; however, the most important thing to understand is that all of the information above is what will drive what the user sees in the WordPress dashboard.

That is, users will see the name, description, and version of the plugin as well as the author's name (which will be linked to the specified URL) when they are presented with the option to activate the plugin.

Adding WordPress's Ajax File

At this point, the plugin will appear in the WordPress Plugin dashboard but it won't actually do anything because we haven't written any code. In order to make that happen, we'll be approaching this particular plugin using the procedural programming approach rather than the object-oriented approach I've used in most of my tutorials.

How We Originally Added Ajax Support

The reason for avoiding object-oriented programming right now is twofold:

1. This is because the plugin is going to be very simple. I'm more interested in focusing on the specified APIs provided by WordPress so you're able to focus on the most important things to focus on in your work.
2. The second part of this series will focus on refactoring this code into an object-oriented system so you can see how all of this might look within the context of a larger system using classes.

Ultimately, this series will be covering both types of programming supported by PHP and WordPress.

Most likely, if you've worked with Ajax in the past, then you've done something like this in order to give your plugin the support to make asynchronous calls:

<?php
add_action( 'wp_head','acme_add_ajax_support' );
function acme_add_ajax_support() {
?>
    <script type="text/javascript">
		var ajaxurl = '<?php echo admin_url( 'admin-ajax.php' ); ?>';
	</script>
<?php
}

This particular method isn't inherently wrong, but it does neglect some of the newer APIs I'll cover momentarily. It also mixes PHP, HTML, and JavaScript all in a single function.

It's not great as it gets the job done, but there is a cleaner way to do this.

How We Add Ajax Support

First, to make sure the plugin can't be directly accessed by anyone, add the following conditional just under the plugin's header:

<?php

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
    die;
}

Note the opening PHP tag will not be necessary since this code will come later in a pre-existing PHP file (it's necessary for syntax highlighting right now).

Next, let's set up a function to include WordPress support for Ajax through the use of some of the existing APIs that don't involve mixing languages. 

Here's what we'll need to do:

1. We're going to create a function responsible for adding Ajax support.
2. We'll hook the function into the wp_enqueue_script action.
3. We will take advantage of the wp_localize_script API call in order to enqueue WordPress's support for Ajax (which comes from admin-ajax.php).

It seems straightforward enough, doesn't it? Note if you have any questions, you can always add them in the comments. Check out the following code to see if you can follow along:

<?php

add_action( 'wp_enqueue_scripts', 'sa_add_ajax_support' );
/**
 * Adds support for WordPress to handle asynchronous requests on both the front-end
 * and the back-end of the website.
 *
 * @since    1.0.0
 */
function sa_add_ajax_support() {
    
	wp_localize_script(
		'ajax-script',
		'sa_demo',
		array(
			'ajaxurl' => admin_url( 'admin-ajax.php' )
		)
	);
	
}

Again, note the opening PHP tag will not be required in the final version of the plugin, as it is here only to take advantage of the syntax highlighting functionality.

With that said, take a look at wp_localize_script. Before examining each parameter, let's review the purpose of this function. From the Codex, the short version is as follows:

Localizes a registered script with data for a JavaScript variable.

The longer description is important, though:

This lets you offer properly localized translations of any strings used in your script. This is necessary because WordPress currently only offers a localization API in PHP, not directly in JavaScript.

Though localization is the primary use, it can be used to make any data available to your script that you can normally only get from the server side of WordPress.

Now review the parameters it accepts:

1. The first parameter is referred to as the handle and is used to uniquely identify the script that's being added to the page.
2. The second parameter is the name, and this is important as it's how you will identify the script throughout your code. You will see this in much more detail later in the tutorial.
3. The third parameter is the data parameter. It refers to an array that will be sent to the browser as a JavaScript object. Since we're passing the URL of a path to a file, Ajax support will be provided.

Notice the first parameter is ajax-script. Keep this in mind when we turn our attention to writing and enqueuing our own JavaScript, as we'll need to use this handle one more time. 

Also remember to make note of the name you've selected for your call to the API, as we'll be using this when working with the client-side code later in this tutorial.

An Important Note About Ajax Support

Notice we're only using the wp_enqueue_script hook and we're not using admin_enqueue_script. This is because ajaxurl is already defined in the dashboard.

This means if you're looking to make Ajax requests in the administration area of WordPress, then you don't need to enqueue anything. Everything we're doing in the context of this tutorial is specifically for the front-end of the website.

Setting Up Your Server-Side Code

Now it's time to write a function your JavaScript will call via Ajax. This can be anything you want it to be, but for the purposes of this plugin we're going to set up a function that will return information about the user who is logged into the site.

The plugin will do the following:

• Make a request to the server asking for information about the current user.
• If the user is logged in to the site, it will return a JSON response of the user's information.
• If the user is not logged in, it will return an error code.

We'll be using the console object that's available in most modern browsers, so make sure you're using Chrome, Safari, or Firefox when working with the JavaScript source you'll be writing.

Making a Request

Now that we've outlined exactly how the code is going to work whenever a user makes an Ajax request to the server, let's start writing a function for doing exactly that. We'll call it sa_get_user_information.

<?php

add_action( 'wp_ajax_get_current_user_info', 'sa_get_current_user_info' );
add_action( 'wp_ajax_nopriv_get_current_user_info', 'sa_get_current_user_info' );
/**
 * Retrieves information about the user who is currently logged into the site.
 *
 * This function is intended to be called via the client-side of the public-facing
 * side of the site.
 *
 * @since    1.0.0
 */
function sa_get_current_user_info() {

}

The function's implementation will come later in this tutorial, but the primary takeaway from the code above is that we've hooked into both wp_ajax_get_current_user_info and wp_ajax_nopriv_get_current_user_info. 

These two hooks are well documented in the Codex, but the first hook will allow those who are logged in to the site to access this function. The second hook will allow those who are not logged in to this site to access this function.

Also note everything after wp_ajax_ and wp_ajax_nopriv_ is up to you, as the developer, to define. This will be the name of the function you call from the client-side as you'll see later in this tutorial.

Handling Erroneous Requests

Before implementing the function, the JavaScript source file (that's yet to be written) has been called, and we need to make sure that we're able to handle any errors that may occur.

In our case, the potential errors may be:

1. No one is logged in.
2. The user ID does not exist in the system.

It's highly unlikely the second case will be true, but it will help us to learn more about a few more of the WordPress APIs and how we can take advantage of them for handling erroneous requests.

The first thing to understand is WP_Error. As with many APIs, this is available in the Codex:

Instances of WP_Error store error codes and messages representing one or more errors, and whether or not a variable is an instance of WP_Error can be determined using the is_wp_error() function.

The constructor will accept up to three parameters (though we'll only be using the first two):

1. The first argument is the error code. This is what we can use on the client-side to parse and determine what went wrong. It also allows us to write information to a log file and so on.
2. The second argument is a message that can accompany the error code. This is useful if we want to display a message to the user.
3. The final argument is an array of information, usually error codes and messages. Regardless, we will not be using this during our code.

Next, we'll be sending the results of the errors back to the client using a function called wp_send_json_error. This is really easy to use:

Send a JSON response back to an Ajax request, indicating failure. The response object will always have a success key with the value false. If anything is passed to the function in the $data parameter, it will be encoded as the value for a data key.

By combining both WP_Error and wp_send_json_error, we can create functions that will help us provide error codes to the JavaScript calling the server-side.

For example, let's say we have a function providing an error if the user isn't logged in to the website. This can be achieved using the following function:

<?php

/**
 * Determines if a user is logged into the site using the specified user ID. If not,
 * then the following error code and message will be returned to the client:
 *
 * -2: The visitor is not currently logged into the site.
 *
 * @access   private
 * @since    1.0.0
 *
 * @param    int    $user_id    The current user's ID.
 */
function _sa_user_is_logged_in( $user_id ) {

    if ( 0 === $user_id ) {

		wp_send_json_error(
			new WP_Error( '-2', 'The visitor is not currently logged into the site.' )
		);

	}

}

Notice the function is marked as private even though it's in the global namespace. It's prefixed with an underscore in order to denote this function should be considered private.

We'll revisit this in the next article.

Secondly, we need to handle the case if the user doesn't exist. To do this, we can create a function that does the following:

<?php

/**
 * Determines if a user is logged into the site using the specified user ID. If not,
 * then the following error code and message will be returned to the client:
 *
 * -3: The visitor does not have an account
 *
 * @access   private
 * @since    1.0.0
 *
 * @param    int    $user_id    The current user's ID.
 */
function _sa_user_exists( $user_id ) {

    if ( 0 === $user_id ) {

		wp_send_json_error(
			new WP_Error( '-3', 'The visitor does not have an account with this site.' );
		);

	}

}

We now have two functions, each of which will send information back to the client if something has failed, but what do we do if both of these functions pass?

Handling Successful Requests

If the functions above do not yield any errors, then we need to have a way to send the request back to the client with a successful message and the information that it's requesting.

Namely, we need to send the information back to the client that includes the current user's information in the JSON format.

To do this, we can take advantage of the wp_send_json_success message. It does exactly what you think it would do, too:

Send a JSON response back to an Ajax request, indicating success. The response object will always have a success key with the value true. If anything is passed to the function it will be encoded as the value for a data key.

Let's combine the work we've done thus far to write a function the JavaScript will eventually call and that leverages the two smaller functions we've placed above. In fact, this will be the implementation of the function we left out earlier in this tutorial:

<?php

add_action( 'wp_ajax_get_current_user_info', 'sa_get_current_user_info' );
add_action( 'wp_ajax_nopriv_get_current_user_info', 'sa_get_current_user_info' );
/**
 * Retrieves information about the user who is currently logged into the site.
 *
 * This function is intended to be called via the client-side of the public-facing
 * side of the site.
 *
 * @since    1.0.0
 */
function sa_get_current_user_info() {

    // Grab the current user's ID
	$user_id = get_current_user_id();

    // If the user is logged in and the user exists, return success with the user JSON
	if ( _sa_user_is_logged_in( $user_id ) && _sa_user_exists( $user_id ) ) {

		wp_send_json_success(
			json_encode( get_user_by( 'id', $user_id ) )
		);

	}

}

If the user is logged in and the user exists, then we will send a success message to the client containing the JSON representation of the user. At this point, it's time to write some JavaScript.

The Client-Side Request

First, add a file called frontend.js to the root of your plugin directory. Initially, it should include the following code:

;(function( $ ) {
    'use strict';
	
	$(function() {
		
	});
	
})( jQuery );

The function implementation will be covered momentarily, but we need to make sure we're enqueuing this JavaScript file in the plugin, as well. Return to the function sa_add_ajax_support and add the following above the call to wp_localize_script:

<?php

wp_enqueue_script(
	'ajax-script',
	plugin_dir_url( __FILE__ ) . 'frontend.js',
	array( 'jquery' )
);

Remember this script must have the same handle as the one defined in wp_localize_script. Now we can revisit our JavaScript file and make a call to the server-side code we've been working on throughout this entire article.

In frontend.js, add the following code:

/**
 * This file is responsible for setting up the Ajax request each time
 * a WordPress page is loaded. The page could be the main index page,
 * a single page, or any other type of information that WordPress renders.
 *
 * Once the DOM is ready, it will make an Ajax call to the server where
 * the `get_current_user_info` function is defined and will then handle the
 * response based on the information returned from the request.
 *
 * @since    1.0.0
 */
;(function( $ ) {
    'use strict';

	$(function() {

		/* Make an Ajax call via a GET request to the URL specified in the
		 * wp_enqueue_script call. For the data parameter, pass an object with
		 * the action name of the function we defined to return the user info.
		 */
		$.ajax({

			url:    sa_demo.ajax_url,
			method: 'GET',
			data:   { action: 'get_current_user_info' }

		}).done(function( response ) {

			/* Once the request is done, determine if it was successful or not.
			 * If so, parse the JSON and then render it to the console. Otherwise,
			 * display the content of the failed request to the console.
			 */
			if ( true === response.success ) {

				console.log( JSON.parse( response.data ) );

			} else {

				console.log( response.data );

			}

		});

	});

})( jQuery );

Given the number of comments in the code and assuming you're familiar with writing WordPress plugins and have some experience with Ajax, it should be relatively easy to follow.

In short, the code above makes a call to the server-side when the page is loaded and then writes information to the browser's console about the current user. 

If a user is logged in, then the information is written out to the console in the form of a JavaScript object since it's being parsed from JSON.

If, on the other hand, the user is not logged in, then another object will be written out displaying an error code along with the message, all of which you will be able to see in the console.

Conclusion

By now, you should have a clear understanding of the APIs WordPress has available for working with Ajax requests for users who are logged in to the site, and for those who are not.

Ultimately, our goal should be to write the cleanest, most maintainable code possible so we have the ability to continue to work with this code as we move into the future. Additionally, we should write code like this so others who may touch our codebase have a clear understanding of what we're trying to do and are also using the best practices given our environment.

In this tutorial, I used a procedural form of programming for all of the code that was shared, demonstrated, and provided via GitHub. As previously mentioned, there's nothing inherently wrong with this, but I do think it's worth seeing what this looks like from an object-oriented perspective.

In the next tutorial, we're going to look at refactoring this code into an object-oriented paradigm that also employs WordPress Coding Standards for further documenting our work, and that uses clear file organization to make our writing as clean and clear as possible.

Remember, you can catch all of my courses and tutorials on my profile page, and you can follow me on my blog and/or Twitter at @tommcfarlin where I talk about software development in the context of WordPress and enjoy conversing with others about the same topics (as well as other things, too).

In the meantime, please don't hesitate to leave any questions or comments in the feed below and I'll aim to respond to each of them.