When you’re implementing a protocol, you have to think about server-side ajax functionality and client-side Ajax functionality.

Though they work together to create a complete feature, they have to implement a protocol. And the way they implement the protocol is a bit different depending on which part of the application you’re focused on creating.

That is, the server-side is going to implement functionality and the protocol in one way, and the client-side is going to have its implementation on how it handles the response from the server.

Server-Side Ajax Protocol

In the previous post, I shared a little bit of code (that, again, should not be used in production – and that could stand to be refactored, to be honest) on how the server might respond with a particular protocol.

Specifically, it performs some work and then responds to the client with a message and a numerical ID. In this case, it helps the client-side to know exactly to know the state of the response (via the message) and if it were successful or not (using the ID).

 The Server-Side Ajax Protocol

If only all protocols could be like this one.

Remember, though, that’s just how I opted to simple protocol functionality. When it comes to doing this on a larger scale, it’s helpful to plan it out in a bit more detail. And in the previous post, I said:

I’ll demonstrate a simple example of implementing a protocol on the server-side.

And when I initially drafted this post, it was a lot longer. It was making arguments for certain decisions, arguments against certain decisions, and included other things that didn’t matter that much when comes down to the core idea.

So I stopped, selected all the text, and deleted it.

Ultimately, what I want to how is how to implement a simple protocol class so that when your server-side functionality has to complete some work, all it has to do is something like this:

And the result will be passed back to the browser.

An Example of a Protocol

I’m going to stick with the same basic protocol syntax from an earlier post, but we’re going to implement it in a way that will [hopefully] be easier to read. The initial draft of this class was written using PSR-2, but I’ve adopted the WordPress Coding Standards instead (since, after all, I focus primarily on WordPress)

A Note About Your Environment

This is all done within the context of WordPress. If you’re using another environment then how you send the information back to the client will likely be different. And that’s fine.

Defining The Protocol

Previously, we said that the protocol could have three states:

  1. complete
  2. incomplete
  3. does_not_exist

Specifically, each of these refers to the state of a function’s ability to complete its action. Next, each of these states is associated with a number where the number refers to which file it’s reading.

In our example’s case, these can range from 0 to some maximum number of files to process. So what would a protocol, on the server-side, look like?

First, using strings to echo information back to the server in the form of, say, “complete:5” is a bit clunky. That’s why it helps to have a protocol defined. Once defined, you can encapsulate it into a class and make simple calls like the one shown above.

One might be to use constants so that you’re responding with something like STATE. The problem with this is that it doesn’t include the identifier of the file. To include that, we could still do something like STATE:5. Even then, we have to do string concatenation.

Though that’s not bad, it’s a little less common that what we see in Ajax responses. Instead, it’s more common to use JSON. Luckily, in PHP we have the ability to create a JSON object from an array.

Creating a Protocol Class

And since we’re using object-oriented programming, we can create a class that’s designed to implement this protocol. The class would need to do the following:

  1. maintain an array that holds the response,
  2. determine if the given response was valid,
  3. gracefully handle the case if the response is not valid,
  4. produce a JSON response to return to the client.

Given all of the above, the class may have a similar implementation:

The code comments should do a decent job of explaining what each function is doing (but given that I wrote the code, that’s what I would say, right?)

Above, I’ve shown an example of how the class may look when you call it on the server-side. But since there are other public functions, there are other, minor alternatives you can make.

Are There Other Options?

Always. In fact, the code above still may be too rigid. The general approach of building a response, validating a message, and preparing a JSON response is typical.

But determine what constitutes a “correct” protocol is different and mostly depends on the project. So don’t take the above code and try to copy and paste it into your project.

Instead, if you opt to use it, use it as an example or a guide for how to implement something in your work.

What About The Client-Side?

As stated earlier in the article, the client-side will implement its functionality and response to how the server-side Ajax functionality responds to the initial request.

So in the next part of this series, we’ll look at how the JavaScript that sends and receives the information handles what the server sends back to it.

Series Posts

  1. Protocol Syntax
  2. The Server-Side Ajax Protocol
  3. The Client-Side Ajax Protocol