3.2.5. Hooks

Data Source Eng Data Source

K4 позволяет программисту выполнять требуемую функциональность до или после нужных событий в системе. Например можно удалять файл картинки с жёсткого диска при удалении записи о картинке из базы данных. Данная возможность реализована через механизм, называемый «hooks».

Hook - это событие (event), которое будет выполняться до или после того события, с которым он связан по средством ключа в массиве Hooks, находящегося в unit config файле. Количество hooks на одно и то же событие не ограничено. Условные обозначения, использованные в данной статье:

  • текущий unit config - это тот unit config, в котором описывается сам hook

  • главное событие - событие, которое приводит к вызову hook

Правила хорошего тона

  • hook должен работать с данными того unit config, в котором он объявлен или с данными главного события

  • hook и то, событие, с которым он связан не должны находиться в одном обработчике событий (т.е. чтобы значение ключей HookToPrefix и DoPrefix не совпадало)

Доступ к главному событию из тела hook производиться через конструкцию

$master_event =& $event->MasterEvent;

Добавление hook

Hook можно добавить использую приведённый ниже код:

'Hooks' => Array (
    Array (
        'Mode' => hAFTER,
        'Conditional' => false,
        'HookToPrefix' => '#PARENT#',
        'HookToSpecial' => '*',
        'HookToEvent' => Array ('OnAfterItemDelete'),
        'DoPrefix' => '',
        'DoSpecial' => '',
        'DoEvent' => 'OnDeleteForeignRelations',
    ),
),

Все указанные выше ключи (при объявлении hook) обязательны. Если требуется на время выключить hook, то надо закомментировать его объявление полностью, а не только ключ DoEvent к примеру. Все ключи начинающиеся с HookTo относятся к заданию главного события, а ключи, начинающиеся с Do описывают какое событие будет вызываться.

название опции

описание опции
Mode (int)

Когда будет выполняться hook относительно главного события (к которому он привязан):

  • hBEFORE - выполняться до основного события (в таких hooks можно отменять вызов основного события);

  • hAFTER - выполняться после основного события (будут выполняться только если основное события успешно завешилось).
Conditional (boolean)

  • true - выполняться только при наличии, в $_REQUEST, данных от префикса из опции DoPrefix;

  • false - выполняться всегда
HookToPrefix (string)

Префикс, для которого создан hook.
HookToSpecial (string)

Special при котором будет срабатывать hook.
HookToEvent (array)

Список событий с которыми данный hook будет связан (будет выполняться до или после них).
DoPrefix (string)

Префикс того unit config, у которого будет выполняться hook (т.е. где он определён).
DoSpecial (string)

Special, с которым вызывать событие из опции DoEvent.
DoEvent (string)

Событие, которое должно выполняться когда сработает hook.

Специальные значения опций

Для более гибкого (flexible) определения hook рекомендуется применять следующие специальные значения для опций при его объявлении:

  • HookToPrefix = '#PARENT#' - использовать значение ключа ParentPrefix текущего unit config;

  • HookToSpecial = '*' - надо вызывать данный hook при любом Special у главного события;

  • DoPrefix = '' - событие из DoEvent ключа находится в обработчике событий заданном в текущем unit config;

  • DoSpecial = '*' - использовать тот Special, с которым вызвано главное событие.

Добавлено в версии 5.0.0.

  • HookToPrefix = '*' - любой префикс (т.е. выполняться для всех, зарегистрированных в системе префиксов);