ThickBox API: Modal Window in WordPress Admin

In WordPress, there is a thing called ThickBox — an API for creating modal windows in the admin area (popups). Such a window, for example, can be seen when clicking the "Details" button on the plugins page. It is very easy to use and, as usual, the settings are quite flexible.

The API is based on the ThickBox jQuery library, which was authored by Cody Lindley. However, the code has been rewritten specifically for WP.

ThickBox is well suited for themes and plugins, as in the event of changes during a WP update, the modal windows will continue to work and there is no need to worry about support and backward compatibility.

Using ThickBox

To create a modal window (thickbox), two things need to be done:

1. Include the ThickBox script in PHP by calling the function add_thickbox().

2. Add a link in HTML (the <a> tag) that will open the modal window. The link should have:
   • The class thickbox: class="thickbox".
   • Additional query parameters should be added to the URL (href attribute).

Modal Window Parameters

Query parameters added to the href attribute of the link opening the modal window:

width

The width of the modal window in pixels.

height

The height of the modal window in pixels.

TB_iframe

Specify this parameter and set its value to true if the content of the URL link needs to be loaded in an iframe. That is, the URL will look like this: http://example.com?TB_iframe=true&width=600&height=550. In this case, the content of http://example.com will be shown in the modal window, within an iframe.

In this case, there is no need to create the modal window element in the HTML of the current page. WP will handle everything automatically.

TB_inline

When using this parameter instead of TB_iframe, the modal window will show a pre-created HTML element with the id specified in the inlineId parameter. That is, the URL should look like this: /?TB_inline&inlineId=my_id&width=600&height=550.

In this case, a DIV element with id=my_id needs to be created.

<div id="my_id" style="display:none;">
	<p>
	   Modal window content
	</p>
</div>

It is important that the content inside the my_id element is inside another element. Above, it is the <p> tag.
Incorrect:

<div id="my_id" style="display:none;">
   Modal window content
</div>

Examples of Creating Modal Windows

#1 Inline Modal Window, Content taken from the current page

<?php add_thickbox(); ?>

<div id="my-modal-id" style="display:none;">
	 <p>
		  <h1>Modal window content.</h1>
	 </p>
</div>

<a href="/?TB_inline&width=600&height=550&inlineId=my-modal-id" class="thickbox">Open Modal Window</a>

As a result, we get such a modal window

#2 Iframe Modal Window, Content taken from the specified URL

<?php add_thickbox(); ?>

<a href="http://example.com?TB_iframe=true&width=600&height=550" class="thickbox">Open Modal Window</a>

#3 Opening a Modal Window through a JS function

Suppose we want to use an inline modal window, but replace the content of this window using AJAX. Unfortunately, the API does not have an event when the modal window is displayed (it exists for the iframe variant, but not for inline).

We can use the JS function tb_show( 'Window Title', URL ), which is part of the API.

Example:

<?php add_thickbox(); ?>

<div id="my-modal-id" style="display:none;">
	 <p>
		  Modal window content.
	 </p>
</div>

<a href="#" class="modal-init-js" onclick="return window.eduResModalShow(this);">Open Modal Window</a>

And now the additional JS code, using tb_show() and creating an AJAX request.

jQuery(document).ready(function($){

	var $modal = $('#my-modal-id');
	var $modalCont = $modal.find('>*');

	// step 1 - displaying the modal window and selecting the editing object
	window.eduResModalShow = function(that){

		tb_show( 'Modal Window Title', '/?TB_inline&inlineId=my-modal-id&width=700&height=500' );

		// AJAX request to load the window content
		$modalCont.html('loading...');
		ajaxs( 'edu_results_modal_html', { user_id: 5 }, function(html){
			$modalCont.html(html);
		});

		return false; // for the link
	}

});

Notes

The JS code is located in the file

/wp-includes/js/thickbox/thickbox.js

HTML code that is automatically created

<div id='TB_title'>
	<div id='TB_ajaxWindowTitle'>Title</div>
	<div id='TB_closeAjaxWindow'>
		<button type='button' id='TB_closeWindowButton'><span class='tb-close-icon'></span></button>
	</div>
</div>

<div id='TB_ajaxContent'></div>

The trigger for the modal window can be

HTML tags: <a>, <area>, and <input>. For initialization, each tag must have class="thickbox".

For <a>, the URL and parameters are specified in the href attribute. For <area> and <input>, they are specified in the alt attribute.

Modal Window Title

It can be specified in the title or name attributes of the element that opens the window (trigger).

JS Events

// removed
jQuery( 'body' ).trigger( 'thickbox:removed' );

// unloaded
jQuery( '#TB_window' ).trigger( 'tb_unload' )

// loaded
jQuery( '#TB_window' ).trigger( 'thickbox:iframe:loaded' );