From In-Portal Developers Guide

Revision as of 13:59, 25 December 2008

JavaScript классы
Статьи в этой категории
AjaxDropdownPreloader DropDownMapper

Часто на форме редактирования возникает необходимость вывести два выпадающих меню (далее ВМ), где набор опций второго ВМ напрямую зависит от выбранной в первом ВМ опции. Причем требуется динамическое обновление опций зависимого ВМ без отправки (submit) формы на сервер. Вышеописанную функциональность можно самостоятельно реализовать стандартными средствами HTML и Javascript, однако рекомендуется использовать уже написанный JavaScript класс AjaxDropdownPreloader, который её реализует.

При изменении значения в главном ВМ, отсылается AJAX запрос на сервер. Сервер выполняет необходимые расчёты и получает новый набор опций для подчиненного ВМ. Полученный набор опций возвращается в виде XML документа на страницу, которая послала AJAX запрос. Далее происходит обработка полученного XML документа и замена опций подчиненного ВМ средствами JavaScript на стороне клиента.

Параметры инициализации

Для успешной реализации связи между двумя ВМ необходимо создать экземпляр класса AjaxDropdownPreloader, передав ему параметры, описанные в приведённой ниже таблице.

<field_options>
	<option>ID1</option>
	<option>ID2</option>
</field_options>

<inp2:prefix_InputName field="#FIELD#"/>
// вернёт строку вида: prefix[ID][#FIELD#]

Настройка шаблона

Для примера рассматривается стандартная форма редактирования с двумя ВМ:

• MainField - главное ВМ;
• DependentField - зависимое и ВМ.

При изменении выбранного значения в поле MainField срабатывает событие onchange и через него подгружаются соответствующие опции в поле DependentField. После выполнения приведённых ниже шагов настройку шаблона можно считать завершенной.

• Добавить элементы ВМ:

<inp2:m_RenderElement name="inp_edit_options" prefix="sample-prefix" field="MainField" title="la_fld_MainField"/>
<inp2:m_RenderElement name="inp_edit_options" prefix="sample-prefix" field="DependentField" title="la_fld_DependentField"/>

• Создать экземпляр класса AjaxDropdownPreloader:

var DependentFieldPreloader = new AjaxDropdownPreloader(
	'<inp2:m_Link template="dummy" sample-prefix_event="OnQueryDependentXML" pass="m,sample-prefix" filter_value="#FILTER_VALUE#" no_amp="1"/>',
	'<inp2:sample-prefix_InputName field="#FIELD#"/>', 'MainField', 'DependentField'
);

• Назначить событие onchange для главного ВМ:

addEvent(DependentFieldPreloader.getControl('MainField'), 'change', function() {DependentFieldPreloader.Query()});

• Отфильтровать значения для зависимого ВМ сразу после загрузки страницы.

Application.setHook('m:OnAfterWindowLoad', function () { DependentFieldPreloader.Query(); });

Весь приведённый выше JavaScript код нужно писать после того, как на форме будут отображены элементы, с которыми он работает. Самое оптимальное для этого место перед подключением шаблона "incs/footer". Это наглядно будет показано на ниже приведённом примере.

<script type="text/javascript">
	// javascript code here
</script>
 
<inp2:m_include t="incs/footer"/>

В данном случае переданный шаблон "dummy" использоваться не будет (его даже может не существовать), а вся подготовка XML документа будет происходить в событии OnQueryDependentXML.

Настройка обработчика событий

В обработчик событий от префикса "sample-prefix" необходимо добавить событие OnQueryDependentXML (указанное на шаблоне редактирования), которое в результате своей работы будет возвращать в поток вывода (output stream) XML документ. Возвращаемый XML документ будет в последствии обрабатывается классом AjaxDropdownPreloader и зависимое ВМ будет заполняется опциями на стороне клиента. После выполнения всех ниже приведённых шагов можно считать настройку обработчика событий завершённой.

Добавить тело события OnQueryDependentXML в обработчик событий от префикса "sample-prefix":

/**
 * [AJAX] Метод для получения отфильтрованных опций в виде XML документа.
 *
 * @param kEvent $event
 */
function OnQueryDependentXML(&$event)
{
	$event->status = erSTOP;
 
	$filter_value = $this->Application->GetVar('filter_value');
	if (!$filter_value || ($this->Application->GetVar('ajax') != 'yes')) {
		return ;
	}
 
	$sql = 'SELECT DependentTable.FieldId
		FROM DependentTable
		WHERE DependentTable.MainId = ' . $filter_value;
	$dependent_ids = $this->Conn->GetCol($sql);
 
	$xml = '';
	foreach ($dependent_ids as $id) {
		$xml .= '<option>' . $id . '</option>';
	}
	$xml = '<field_options>' . $xml . '</field_options>';
 
	$this->Application->XMLHeader();
	echo $xml;
}

Событие OnQueryDependentXML необходимо добавить в метод mapPermissions, который обеспечит проверку наличия у пользователя необходимых прав доступа для вызова данного события:

/**
 * Метод связывающий события и права, необходимые для их выполнения. 
 *
 */
function mapPermissions()
{
	parent::mapPermissions();
 
	$permissions = Array (
		'OnQueryDependentXML' => Array ('self' => 'view'),
	);
 
	$this->permMapping = array_merge($this->permMapping, $permissions);
}

Также следует обратить внимание на некоторые, описанные ниже, приёмы, которые использовались при написании события OnQueryDependentXML.

• В начале события рекомендуется установить статус его выполнения в erSTOP. Это укажет на то, что по окончания выполнения события не нужно показывать содержание переданного шаблона (в данном случае это "dummy"):

$event->status = erSTOP;

• В начале события написать код, который позволит игнорировать запросы, которые будут делать поисковые системы:

if ($this->Application->GetVar('ajax') != 'yes') {
	return ;
}

Параметр "ajax" добавляется автоматически при отправлении каждого AJAX запроса. Если поисковая система где-то найдёт ссылку, в которой указано данное событие, то зайдя на неё тело события выполнено не будет.

• Перед выводом XML документа на экран необходимо послать браузеру соответствующий заголовок. Сделать это можно при помощи метода Application::XMLHeader:

$this->Application->XMLHeader();

Конечно такой заголовок слать не нужно, если не планируется возвращать XML документ.

Использование метода AfterProcess

В классе AjaxDropdownPreloader также доступен абстрактный метод AfterProcess. Данный метод рекомендуется переопределять, когда требуется выполнение специфической функциональности после выполнения фильтраций опций зависимого ВМ.

См. также

• DropDownMapper