I’ve talked about Ajax in WordPress in previous posts and it’s pretty well-documented in the Codex, so I don’t want to belabor the point on how to actually implement it.

Ajax in WordPress

Instead, the point of this post is to discuss how to implement custom response messages – or custom error messages – so you’re able to try/catch or gracefully handle the case when a request to the server fails.

That is, given the examples in the previous links we know how to implement Ajax in WordPress, but how do we handle the cases when something goes wrong? It’s not enough to simply write something out via console.log – after all, that’s meaningless to the user – but wouldn’t it be nice to actually display some type of message to let the user know what went wrong and how they can address it?

Custom Responses with Ajax in WordPress

First, the general summary of how to introduce Ajax is pretty straightforward (once you’ve gotten through the initial documentation on it):

  1. Define a custom handler on the server-side
  2. Determine if said handler should be accessible by the public, by those who are logged in, or both
  3. Setup your JavaScript to make a call to the handler with `ajaxurl` being the destination
  4. Specify any data necessary to do its work
  5. Have an anonymous function setup to handle the response from the server

If you’re using jQuery – and I mention this since it’s what’s bundled with WordPress – then you can opt to use $.ajax, $.post, or $.get.

Personally, I’m a fan of using one of the latter two since it makes the code absolutely clear as to if I’m trying to send information to server or if I’m trying to receive information to the server.

The general setup for the server-side will look something like this:

And the general setup for the client-side will look something like this:

But when you’re sending data to the server and you’re sending a response back to the client, there’s always the chance something could go wrong. And in that case, we need to be able to gracefully handle that situation.

Note in the code above, you see we’re adding support for ajaxurl into the WordPress project, and we’re sending a basic call to the acme_user_has_voted function via a $_GET request that includes the post ID.

I did, however, leave out how the response is handled. This will be covered in more detail later, but suffice it to say that whereas in the code I’m choosing to echo a boolean, you can choose to echo any number of things that will help make your client-side code more robust.

What Went Wrong?

Ideally, we need to be able to determine what went wrong and this usually occurs on the server-side. That is, the client-side is generally responsible for sending information to the server.

So if it sends…

  • Malformed information
  • Doesn’t send any information at all
  • Or sends the wrong information

Then we need to be able to handle it.

For example, maybe the current post ID needs to be sent to the server along with, say, the contents of an element somewhere on the page. Or maybe the page title and the value of a certain set of input elements is supposed to be sent to the server.

There are a number of places in which this could fail, right? Maybe the value of the post ID isn’t set anywhere for us to retrieve it. Or perhaps the user didn’t actually select anything from available input elements to send across the wire.

In cases like this, the server is not going to be able to perform its work because it doesn’t have it the information it needs. So what now?

How Should We Handle This?

In general programming practices, it’s standard practice to do one of two things:

  1. Catch the exception that occurs
  2. Throw an exception for the caller to catch

Because of the way the Ajax system is setup in WordPress, we can’t really throw a true exception, but we can define error codes our JavaScript can read, interpret, and then handle appropriately.

Let’s say, for example, the post ID wasn’t sent to the server through it was expected to be there before the server could do its work (just like how we have setup in the sample code above).

Before we do any work, we need to check to see if the error code is there. If so, then we need to handle them however best suits the project. Sometimes this is going to be displaying an error message, sometimes it’s going to be toggling an element, something it will be throwing an exception, and other times it will be something else.

A Strategy For Error Codes

Whatever the case is for your site, application, or project is going to vary based on what it is you’re building. However, the chance of something failing when the user is trying to send something across the wire and then having to handle the response is high.

There are a lot of variables that come into play:

  • User input
  • Network connection
  • Data in the database
  • Quality of error handling in the source code on the server-side and client-side
  • …and more

So coming up with a strategy for error codes and how to handle them is something that’s a topic in and of itself. In the next post, I’ll talk about the strategies I employ and what has worked for me.

It won’t be a definitive guide by any stretch of the imagination, but over my time in working with WordPress and Ajax, it’s something that’s proved to be valuable not only in terms of handling errors but in terms of logging information so users can easily send me data so I can easily identify the point of failure.

If you're reading this post in an RSS reader, don't forget to click on the "gist" link to see the code for the post.