Adding WordPress Modal Dialogs (With Built in Libraries)

Whenever it comes to developing solutions for clients, there are going to be times when you’re likely tasked with displaying information in WordPress modal dialogs.

There are a lot of solutions available for doing this and the more familiar you are with JavaScript, various libraries, and the libraries that they have available, the harder (or maybe it’s even easier) it is to choose which one to use.

But WordPress has infrastructure built-in that makes it trivial to incorporate functionality into WordPress. So in three upcoming posts, I’ll cover the following:

  1. How to incorporate WordPress modal dialogs using built-in libraries,
  2. Populating the modal dialogs with data,
  3. Populating the modal dialog with dynamic data via Ajax.

Because of the nature of the series, the posts won’t be back-to-back, but they’ll all use a unique tag that you can use to bookmark and refer to as a series once the posts are complete.

With that said, let’s talk about easily incorporating WordPress modal dialogs with built-in libraries.

WordPress Modal Dialogs, Part 1

To get started, I’m assuming that you have the basic foundation of an administration page in place.

On Plugin Pages

That is, you have all you need to get a plugin setup, activated, and then a page displaying via a menu or submenu.

If not, check out this post to see how to get started.

Once you have that done, you’ll need the basic infrastructure for a plugin page. This page may be used for simply displaying information or it may be used both for displaying information and giving the user the ability to save options.

For this tutorial, I’m not particularly interested in giving the user the ability to save options. Instead, we need to create an anchor that will display a modal dialog whenever it’s clicked.

And the data that it will contain will be covered in a later tutorial.

A Sample Plugin Page

At this point, I’m assuming you have a plugin page. A basic structure for it can look like this:

From there, there are two things that are necessary:

  1. incorporating the Thickbox library
  2. adding an anchor and container that will display a modal dialog

To incorporate the Thickbox library into your plugin page, simply add this tag. If you’re following any coding standards, then your page likely has a docblock at the top of the page. This is where I normally add the code.

The add_thickbox function is one provided by WordPress that does the following:

Enqueues the default ThickBox js and css.

A bit vague, right? Technically the longer description is:

ThickBox is a webpage UI dialog widget written in JavaScript on top of the jQuery library. Its function is to show a single image, multiple images, inline content, iframed content, or content served through AJAX in a hybrid modal.

And if you’re interested in the Thickbox library on its own you can see it on this page.

WordPress Modal Dialogs: Thickbox

Anyway, back to the page. Now that I’m adding it to my plugin page using the WordPress API function,  my page looks something like this:

Next, creating the anchor and the element for displaying data go hand-in-hand with one another namely because the anchor needs the ID of the element that will serve as the modal dialog.

The anchor needs the following information:

  • the ID of the element that will display the modal,
  • the dimensions of the said modal dialog

For this example, I’m going to set up a dialog that displaying at 800×600 pixels and it will have the ID of acme-modal-dialog.

Note: Remember it’s a good idea to prefix your elements with something related to the name of your plugin, so no conflicts arise.

So I’ll create an anchor that looks like this:

And then I’ll create an element like this:

And the above code is what the final version of the plugin page will look like this, as well. When you click on the anchor, an empty dialog should appear with the dimensions specified (that is, 800×600 pixels).

WordPress Modal Dialogs: Modal Dialog

Of course, it will be empty in that it won’t be displaying any data.

Displaying Data

In the next post in the series, I’ll walk through how to display data within the context of the dialog.

It’s easy, but it’s a good starting point if you’re looking to begin incorporating dynamic data via the REST API or Ajax. But I’ll cover that before the end of this.