ThickBox API: модальное окно в админке

В WordPress есть такая штука как ThickBox — это API для создания модальных окон в админке (попапов, popup). Такое окно, например, можно видеть при нажатии на кнопку «Детали» на странице плагинов. Пользоваться очень просто и как обычно, настройки довольно гибки.

API основан на библиотеке ThickBox jQuery, автором которой является Cody Lindley, однако код был переписан специально для WP.

ThickBox хорошо подойдет для тем и плагинов, так как в случае изменений при очередном обновлении WP, модальные окна будут по прежнему работать и не надо переживать о поддержке и обратной совместимости.

Использование ThickBox

Для создания модального окна (thickbox) нужно сделать две вещи:

1. Подключить скрипт ThickBox в PHP, вызвав функцию add_thickbox().

2. Добавить в HTML ссылку (тег <a>), которая будет открывать модальное окно. Ссылка должна иметь:
   • Класс thickbox: class="thickbox".
   • В URL (атрибут href) нужно добавить дополнительные параметры запроса.

Параметры модального окна

Параметры запроса, которые добавляются в атрибут href ссылки открывающей модальное окно:

width

Ширина модального окна в пикселях.

height

Высота модального окна в пикселях.

TB_iframe

Указываем этот параметр и ставим ему значение true, если нужно загрузить контент указанной в URL ссылки в iframe. Т.е. URL будет выглядеть так: http://example.com?TB_iframe=true&width=600&height=550. Так контент http://example.com будем показан в модальном окне, в iframe.

В этом случае не нужно создавать сам элемент модального окна в HTML текущей страницы. ВП сделает все автоматом.

TB_inline

При использовании этого параметра вместо TB_iframe модальное окно покажет заранее созданный HTML элемент с id атрибутом указанным в параметре inlineId. Т.е. URL должен выглядеть так: /?TB_inline&inlineId=my_id&width=600&height=550.

В этом случае нужно создать DIV элемент с id=my_id.

<div id="my_id" style="display:none;">
	<p>
	   Контент модального окна
	</p>
</div>

Важно чтобы контент внутри элемента my_id находился внутри другого элемента. Выше это тег <p>.
Так неправильно:

<div id="my_id" style="display:none;">
   Контент модального окна
</div>

Примеры создания модальных окон

#1 inline модальное окно, контент которого берется из текущей страницы

<?php add_thickbox(); ?>

<div id="my-modal-id" style="display:none;">
	 <p>
		  Контент модального окна.
	 </p>
</div>

<a href="/?TB_inline&width=600&height=550&inlineId=my-modal-id" class="thickbox">Открыть модальное окно</a>

В результате получим такое модальное окно

#2 iframe модальное окно, контент которого берется по указанному URL

<?php add_thickbox(); ?>

<a href="http://example.com?TB_iframe=true&width=600&height=550" class="thickbox">Открыть модальное окно</a>

#3 Вызов модального окна через JS функцию

Допустим, мы хотим использовать inline модальное окно, но контент этого окна заменять через AJAX. К сожалению, в API нет события когда модальное окно показывается (оно есть для iframe варианта, то не для inline).

Мы можем использовать JS функцию tb_show( 'Заголовок окна', URL ), она входит в состав апи.

Пример:

<?php add_thickbox(); ?>

<div id="my-modal-id" style="display:none;">
	 <p>
		  Контент модального окна.
	 </p>
</div>

<a href="#" class="modal-init-js" onclick="return window.eduResModalShow(this);">Открыть модальное окно</a>

И теперь дополняющий JS код, где используется tb_show() и создается AJAX запрос.

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

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

	// шаг 1 - показ модального окна и выбор объкта редактирвоания
	window.eduResModalShow = function(that){

		tb_show( 'Заголовок модального окна', '/?TB_inline&inlineId=my-modal-id&width=700&height=500' );

		// AJAX запрос для загрузки контента окна
		$modalCont.html('загружаю...');
		ajaxs( 'edu_results_modal_html', { user_id: 5 }, function(html){
			$modalCont.html(html);
		});

		return false; // для ссылки
	}

});

Заметки

JS код находится в файле

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

HTML код который создается автоматически

<div id='TB_title'>
	<div id='TB_ajaxWindowTitle'>Заголовок</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>

Триггером модального окна может быть

HTML тег: <a>, <area> и <input>. Для инициализации каждый тег должен иметь class="thickbox".

Для <a> URL и параметры указываются в атрибуте href. Для <area> и <input> в атрибуте alt.

Заголовок модального окна

Можно указать в атрибутах title или name элемента открывающего окно (триггера).

JS события

// удалено
jQuery( 'body' ).trigger( 'thickbox:removed' );

// закрыто
jQuery( '#TB_window' ).trigger( 'tb_unload' )

// загружено
jQuery( '#TB_window' ).trigger( 'thickbox:iframe:loaded' );