События

События позволяют контролировать процесс работы сторонних модулей. Поскольку события вызываются неявно, они создают нелинейнойсть кода, которую можно отследить только через стек вызовов событий и список обработчиков. Поэтому события рекомендуется использовать только тогда, когда невозможен прямой вызов объектов.

Для того, чтобы обработать некоторое событие, необходимо зарегистрировать обработчик события AMI_Event::addHandler и указать, событие какого модуля необходимо обработать.

Для того чтобы передать параметры в дальнейшую цепочку событий, необходимо в обработчике события вернуть массив входящих параметров $aEvent. Возвращаемые результаты необходимо добавить в данный возвращаемый параметр.

Для того чтобы остановить дальнейшее выполнение цепочки событий, необходимо в качестве элемента массива вернуть $aEvent['_break_event'] = true;

10.1 События получения списка элементов

10.1.1 on_table_get_list

Инициализация получения списка объектов. Метод удобно использовать для динамического добавления зависимостей моделей (соединение таблиц).

Параметры:

Пример обработчика события. Включение активности у зависимой модели с алиасом «cat»:

public function handleTableGetList($name, array $aEvent, $handlerModId, $srcModId){
    $oTable = $aEvent[' oTable '];
    if(is_null($oTable->setActiveDependence('cat'))) {
        trigger_error('Categories table not found', E_USER_ERROR);
    }
    return $aEvent;
}
// …
AMI_Event::addHandler('on_table_get_list', array($this, 'handleTableGetList'), $modId);

10.1.2 on_query_add_table

Событие, вызываемое при добавлении таблицы в запрос, создаваемый моделью таблицы. Событие вызывается при получении объекта модели списка или модели элемента.

Например, событие возникает при вызове getList(), если у модели oModel есть зависимые модели:

$oModelList = $this->oModel->getList()->addColumns($aColumns)->load();

Независимо от того, добавляется таблица основной модели или зависимой, событие имеет одинаковые параметры.

Пример обработчика события. Фильтрация результатов по языку, если в таблице есть поле «lang»:

 public static function handleFilterLangData($name, array $aEvent, $handlerModId, $srcModId){
    if($aEvent['oTable']->hasField('lang')){
        $aEvent['oQuery']->addWhereDef(
            DB_Query::getSnipplet('AND %s.`lang` = %s')
            ->plain($aEvent['alias'])
            ->q(AMI_Registry::get('lang_data'))
        );
    }
    return $aEvent;
}

// …
AMI_Event::addHandler(
    'on_query_add_table',
    array('AMI_GlobalFilters', 'handleFilterLangData'),
    AMI_Event::MOD_ANY
);

10.1.3 on_query_add_joined_columns

Событие, вызываемое для добавления столбцов в результат запроса, полученного соединением с зависимой моделью.

Например, событие возникает при вызове getList(), если у модели oModel есть зависимые модели:

$oModelList = $this->oModel->getList()->addColumns($aColumns)->load();

Параметры:

Пример обработчика события. Добавление столбцов 'id', 'header' в результат соединения моделей:

public function handleAdmQueryAddJoinedColumns($name, array $aEvent, $handlerModId, $srcModId){
    $aEvent['oList']->addColumns(array('id', 'header'));
    return $aEvent;
}

// …
AMI_Event::addHandler('on_query_add_joined_columns', array($this, 'handleQueryAddJoinedColumns'), $modId);

10.1.4 on_list_recordset

Событие, вызываемое непосредственно перед выполнением запроса получения списка элементов.

Параметры:

Пример обработчика события. Добавление дополнительной фильтрации по категории:

public function handleListRecordset($name, array $aEvent, $handlerModId, $srcModId){
    if($this->idCat > 0) {
        $aEvent['oQuery']->addWhereDef(
            DB_Query::getSnipplet('AND %s.`id` = %s')
            ->plain($this->prefix)
            ->q($this->idCat)
        );
    }
    return $aEvent;
}
// …
AMI_Event::addHandler('on_list_recordset', array($this, 'handleListRecordset'), $modId);

10.1.5 on_before_set_data_model_item

Событие, вызываемое при инициализации модели элемента данными записи из базы данных.

Параметры:

Вызов данного события обязателен для полноценной инициализации расширений модуля (категории, изображения и т.п.).

10.2 on_html_meta_change

Событие, вызываемое при изменении HTML-мета-тегов.

Параметры:

Например, если модуль работает на статичной странице менеджера сайта, получает данные через GET-параметры и нужно, результаты работы модуля индексировались, в обработчике события необходимо проверить, соответствует ли страница, для которой вызвали событие, странице с модулем, и, если да, установить параметр «index» в TRUE:

// _local/front_functions.php
function cstOnHTMLMetaChange($name, array $aEvent, $handlerModId, $srcModId){
    if(
        $aEvent['name'] == ‘robots’ &&
        // номер страницы в менеджере сайта, на которой работает моудль
        AMI_Registry::get('page/id') == 20088
    ){
        $aEvent['content'] = 'index,follow';
    }
    return $aEvent;
}
AMI_Event::addHandler('on_html_meta_change', 'cstOnHTMLMetaChange', AMI_Event::MOD_ANY);