In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Hooks

From In-Portal Developers Guide

(Difference between revisions)
Jump to: navigation, search
(Специальные значения опций: дополнение)
m (1 версия)

Revision as of 16:19, 28 February 2009

Unit Configs Unit Configs
Статьи в этой категории

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;
  • HookToPrefix = '*' - любой префикс (т.е. выполняться для всех, зарегистрированных в системе префиксов), доступно с Core v 5.0.0;
  • HookToSpecial = '*' - надо вызывать данный hook при любом Special у главного события;
  • DoPrefix = '' - событие из DoEvent ключа находится в обработчике событий заданном в текущем unit config;
  • DoSpecial = '*' - использовать тот Special, с которым вызвано главное событие.