Advertisement
  1. Code
  2. Creative Coding
Code

A Primer on Ajax in the WordPress Dashboard - Requesting and Responding

by
Languages:
This post is part of a series called A Primer On Ajax in the WordPress Dashboard.
A Primer on Ajax in the WordPress Dashboard - Laying the Foundation

In this two part series, we're taking a look at how to properly introduce Ajax-specific functionality into the WordPress Dashboard.

In the first article in the series, we began working on a plugin that displays a notification as soon as it's activated ... but that's it. In this article, we'll add Ajax-enabled functionality that will allow users to dismiss the message and we'll finish up with a working version of the plugin.

Specifically, we're going to cover all of the things necessary on both the server-side and the client-side that are necessary to process an Ajax request and respond appropriately.

Finally, we'll review a checklist of items that all Ajax-based WordPress functionality should have to make sure that you properly employ the API in future projects.


Remember the Nonce

Before we get started, it's important to make sure that you have the nonce value in the function that renders your notification method. For review, here's the function that we included in the first article:

Notice that we're rendering the nonce value using wp_create_nonce in a span element having the ID of ajax-notification-nonce. I bring this up for three reasons:

  1. Nonce values provide security measures and are important when you're making any type of request from the front-end to the back-end.
  2. In my experience, this is one of the things that developers most often leave out of their work - this is meant to make sure we have this covered prior to writing any additional code.
  3. The element containing the nonce value needs a specific ID so that we can easily access it using JavaScript when initiating our Ajax request.

With that, let's get to writing the Ajax functionality.


On to Ajax

Building Ajax-based functionality in the WordPress Dashboard typically includes four key points:

  • Some JavaScript functionality that will respond to the user's event and send it to the server
  • A server-side callback function that is responsible for managing the request coming from the browser
  • Server-side functionality that will send the data back to the browser
  • JavaScript functionality responsible for handling the response

Though there's no particular order in which we need to write this code, we'll just go down the list as it's stated above and work through it.

Sending the Request

The JavaScript code for sending the request is relatively boilerplate stuff, but we need to first outline what it is that we're actually going to do:

  • The user decides to dismiss the notification
  • The user clicks on the dismiss anchor that we've provided
  • JavaScript responds to the event when the user clicks on said anchor
  • JavaScript sends a request to the server

We'll write the code incrementally to make sure that it's easy to follow along. First, we'll start by setting up the code after the window has loaded and we'll make sure that the Ajax notification message is present:

Next, we need to setup an event handler that will fire once the user clicks on the anchor that we've placed in the notification. For this, we need the ID of the message's element - that is, dismiss-ajax-notification.

Because an anchor's default behavior is to try to navigate to its href attribute, we need to also prevent the default action from occurring.

At this point, we're ready to actually send the request to the server. To do this, we'll be using the jQuery post function. We'll be passing it three arguments:

  • The URL of the address to which the request should be sent. This is a global value provided by WordPress. It's stored in the ajaxurl variable
  • The hash of options to send to the server. This includes the action - or the function - to fire on the server and the nonce value for validation
  • The function used to handle the response

Let's write out all of this now (including stubbing out the response function) and then we'll hop over to the server-side code.

Recall earlier that I said we'd need to know the ID of the field containing the nonce value - that is, ajax-notification-nonce. Notice above that we're grabbing the text value of that element and sending it to the server as the value of the nonce key.

The second thing to notice is that we're sending along an action key that has the value of hide_admin_notification. This is a function that we need to write on the server as it's what will be responsible for actually hiding the notification.

Handling the Request

In our plugin file, we need to create a function that has the name as the action value mentioned above: hide_admin_notification.

As usual, I like to talk about what the function is going to do before writing any code. In this case, here's what needs to be done:

  • We need to make sure the incoming nonce is correct; otherwise, we don't want to execute any code
  • We need to update the option that we created in the first article to set the dismiss to false
  • We need to send a value back to the browser so that it can respond appropriately to the function

Here's the code for making that happen:

It's relatively simple, isn't it? The key thing to understand is that we're sending the value of '1' in the context of die if the option is successfully updated; otherwise, we send the value of '0'. This will allow us to read the value in the response on the browser to determine how best to respond.

Obviously, if the returned value is 1, then we can hide the notification.

Before hopping back into the JavaScript, we need to make sure that we wire this function up using the appropriate hook. So, in the plugin's constructor, let's add a line for add_action:

The key thing to note here is that the tag for the function is labeled 'wp_ajax_hide_admin_notification'.

If you're working with Ajax in the WordPress dashboard, then your hook must be added with the wp_ajax_ prefix and it should end with the name of the function.

This is easily the second most important thing I see developers miss when working on Ajax-based code.

From here, we're ready to hop back into the client-side code.

Handling the Response

Finally, we're ready to handle the response. This is easy: If the server responds with a 1, then we'll hide; otherwise, we won't do anything.

Granted, the best practice would be to display an error message or some type of feedback to let the user know that something went wrong, but the main point of the article is to demonstrate Ajax in WordPress so we'll simply change out the class name from updated to error.

Here's what needs to be added to the JavaScript source to handle the response:

And that's really it. The full JavaScript source should look like this:

And the plugin's PHP should look like this:


Conclusion

You can grab the plugin on GitHub. For reference, be sure to review the following resources:

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.