The Ajax protocol syntax is something that was briefly mentioned in the first post in this series. One of the things mentioned is that a protocol required:

Syntax which should be consistent.

That is, it’s not something that’s defined for us. On the contrary, we have the ability to define the Ajax protocol we want to use on a project-specific basis. I’m a fan of this because I find that different projects call for different semantics (in a number of ways, protocols not excluded).

Ajax Protocol Syntax: The phone

An early protocol. Kind of awesome. Product of a bygone era.

But, if you so choose, you can implement the same protocol syntax across your entire set of projects (though I’d find it difficult to think one protocol would match all use cases).

Regardless, this post will cover the first step in establishing an Ajax protocol syntax that you may (or may not) use in a WordPress project.

Defining The Ajax Protocol Syntax

Defining a protocol should be simple. Sure, it sounds more complicated because, I don’t know, we’re using words like “protocol” and “syntax” which are usually reserved for more sophisticated forms of data transmission or languages.

But that’s just the thing:

We are working with data transmission and we’re doing so in two different programming languages.

Anyway, there’s no single right way to do it. Instead, you can define how it should be implemented.

As mentioned, I don’t have a consistent way of implementing a protocol. But in a recent project, I’ve been working with asynchronously reading files and sending information back to the client based on if the read was successful or not.

Thus, the protocol consists of the state of reading the file and the number of the file (out of the total number of files) that are read. This looks something like this:

state_of_function:file_number.

This way, when the response comes back to the client, I can split the response on the colon and then determine what course of action to take.

So if I’m successful at reading, say, the fifth file, then I would send completed:5 back to the client. If, on the other hand, there’s a problem with reading the file (and the necessary work has been done on the server) then I might send incomplete:5 or does_not_exist:5.

An example of some of my PHP looks like this:

Are there others way to do this? Sure. But does this work for the purposes of this particular project? Yes.

And before thinking there’s a better way to do, remember that requirements dictate a number of things that don’t often get shared in the context of places like a blog post.

And before thinking there’s a better way to do, remember that requirements dictate a number of things that don’t often get shared in the context of places like a blog post.

The Point of Protocol Syntax

Ultimately, you need to make sure you have a small set of messages to handle the first part of the response so you know how to properly respond to them.

That is, you should know how to respond to:

  1. complete
  2. incomplete
  3. does_not_exist

Granted, this is just a subset of my implementation. Yours may vary. It may be simpler, it’s likely more complex. But the principles behind what is demonstrated are the same.

And you need to make sure the second part of the response is a valid filename. For example, if -1 is returned to the client, then perhaps the file did not exist. Or if 0 is returned, then perhaps all of the files have been complete.

Whatever the case, the plan of action should be straightforward:

  1. have the server return a protocol-specific response to its action,
  2. have the client parse the response and handle it gracefully,
  3. take the necessary course of action based on the result of the response.

In the next post, I’ll demonstrate a simple example of implementing a protocol on the server-side. Then, in the final article I’ll take a look at what it’s like to implement code for handling response on the server-side.

It’s exciting stuff, right? I mean, if you’re into this sorta thing. Otherwise, I’m not sure why you even read this far. Regardless, as usual, comments and questions welcome.

Series Posts

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