As far back as 1.0, jQuery has provided a trigger function that allows us to:
Execute all handlers and behaviors attached to the matched elements for the given event type.
But it wasn’t until 1.3 that this particular function became significantly more useful, at least as far as I’m concerned. I say that because that’s when we gained the ability to define custom events and then set handlers for them.
What, though, is a likely use case in which custom jQuery events are useful in the context of WordPress? Off the top of your head, you may be able to come up with many. Or maybe not.
It hasn’t been until lately that I’ve been using them significantly more than usual. So I thought I’d share how I’m using them if for now other reason than showing you how to wire them up to your work.
Custom jQuery Events
If you’re experienced with JavaScript – vanilla or not – you’re likely familiar with basic event handlers. That is, when someone clicks on an element, we have a function set to fire that does something.
Custom jQuery Events are a lot like that except these are events that we define. This means we don’t have to rely on when someone moves their mouse over an element or when they click on an element.
Instead, we can trigger an event and then have a handler set up to response appropriately. Here’s an example.
Preparing for a Custom Event
Let’s say that you’re working on a project and it has an administration page responsible for retrieving data from a third-party API. The flow of control would look something like this:
- The user clicks on a button,
- An Ajax request is initiated and requests information from the third-party,
- While the request is happening, buttons on the screen should be disabled,
- Once the request has complete, buttons can be re-enabled,
- Optionally, a status message can be written to the screen.
For this to happen, it expects that there’s at least one button (as in an input element) and an optional text field or textarea in which the status of the request can happen.
Once the user clicks on the event, we can trigger a custom event. We can call this event acme.ajax.processing. Then, we can then use the done function provided by jQuery to handle anything we want to clean up afterward or we can use our custom function if there’s something we want to handle at the end, too.
For this both, we’ll look at both. So we’ll also have an event called acme.ajax.complete.
So we’re concerned with:
- creating a custom an event,
- triggering it,
- setting up an event handler for it,
- finishing up once the request is complete.
And that’s what we’ll do.
Defining a Custom Event
So when a user clicks on a button, an Ajax request is doing to be made. At the same time, this is also going to trigger the acme.ajax.processing event which will have its event handler.
So first, let’s create the Ajax request. For this, I’m going to assume that the button responsible for triggering the Ajax request is simply referred to as $button:
Notice that the first thing we want to do is trigger the processing event then we make the request.
Handling a Custom Event
Next, we want to make sure that we have an event handler set up to disable the button while the request is happening.
This is easy to do and to keep this simple, and I’m going to disable the button:
Easy, right?
Handling Another Custom Event
Next, we need to handle the situation when the Ajax request is completed. So we need to make sure to trigger the event and then we need to handle the event.
Triggering the event is easy:
And handling the event can be changed to the code we already have:
It can be chained because it’s happening on the document object – not a separate element.
To that end, so it’s much easier to handle.
Just One Example
Of course, this is but one example of how to handle custom jQuery events.
There are plenty of other ways to do this, and you can do some pretty complicated things with it; however, this should provide enough information for what you need on how to work with custom events at a fundamental level.
