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 версия)
Current revision (04:15, 28 November 2010) (view source)
(Trans.)
 
Line 1: Line 1:
{{toc | category = Unit Configs | sortkey = 004.001}}
{{toc | category = Unit Configs | sortkey = 004.001}}
-
K4 позволяет программисту выполнять требуемую функциональность до или после нужных [[K4:Events|событий]] в системе. Например можно удалять файл картинки с жёсткого диска при удалении записи о картинке из базы данных. Данная возможность реализована через механизм, называемый "hooks".
+
Hooks in In-Portal allow to execute any events before or after specific [[K4:Events|events]] in the system. A live example of this would be deleting a physical image from the file-system once data record of the image is deleted from the database. This functionality is implemented using "hooks".
-
Hook - это событие (event), которое будет выполняться до или после того события, с которым он связан по средством ключа '''в массиве Hooks''', находящегося в [[K4:Unit Configs|unit config]] файле. Количество hooks на одно и то же событие не ограничено. Условные обозначения, использованные в данной статье:
+
Hook - is a an event which will be executed before or after the original event it's been hooked to by defining it in '''Hooks''' array in [[K4:Unit Configuration File|Unit Configuration File]]. There is no limit on number of hooks that can be setup for one event.
-
'''текущий unit config''' - это тот unit config, в котором описывается сам hook
+
-
'''главное событие''' - событие, которое приводит к вызову hook
+
-
== Правила хорошего тона ==
+
These are the terms that will be used in this article:
-
* hook должен работать с данными того unit config, в котором он объявлен или с данными главного события
+
-
* hook и то, событие, с которым он связан не должны находиться в одном [[EventHandler:About|обработчике событий]] (т.е. чтобы значение ключей HookToPrefix и DoPrefix '''не совпадало''')
+
-
Доступ к главному событию из тела hook производиться через конструкцию
+
'''Current Unit Config''' - this a unit config where the Hook is defined
 +
'''Main Event''' - event which triggers the Hook
 +
 
 +
== Decencies ==
 +
* hook should work strictly with the dataset of Unit it's been defined in or dataset of Main Event triggered the hook
 +
* hook and Main Event (which triggered the hook) should not be located in the same [[EventHandler:About|Event Handler]] (which means that HookToPrefix and DoPrefix '''can't the same''')
 +
 
 +
Access to Main Event from inside the hooks can be done using the following code:
<source lang="php">
<source lang="php">
$master_event =& $event->MasterEvent;
$master_event =& $event->MasterEvent;
</source>
</source>
-
== Добавление hook ==
+
This will return a link to the object of the Main Event.
-
Hook можно добавить использую приведённый ниже код:
+
 
 +
== Registering a Hook ==
 +
New Hooks can be registered (added) using the code below:
<source lang="php">
<source lang="php">
Line 33: Line 38:
</source>
</source>
-
Все указанные выше ключи (при объявлении hook) обязательны. Если требуется на время выключить hook, то надо '''закомментировать''' его объявление '''полностью''', а не только ключ <code>DoEvent</code> к примеру. Все ключи начинающиеся с <code>'''HookTo'''</code> относятся к заданию главного события, а ключи, начинающиеся с <code>'''Do'''</code> описывают какое событие будет вызываться.
+
All listed above keys are required. In case if hooks needs to be temporarily disabled then it's recommended to '''comment out''' it's '''entire definition''' and not only some parts of it (ie. <code>DoEvent</code>). All array keys starting with <code>'''HookTo'''</code> are related to definition of Main Event while all keys starting to <code>'''Do'''</code> describe which Event will be called once this hook triggered.
{| class="prettytable"
{| class="prettytable"
-
! название опции || описание опции
+
! Option Name || Description
|-
|-
-
| {{ConfigProperty|Mode|int}} || Когда будет выполняться hook относительно главного события (к которому он привязан):
+
| {{ConfigProperty|Mode|int}} || When hook will executed in relation of the Main Event:
-
* <code>hBEFORE</code> - выполняться до основного события (в таких hooks можно отменять вызов основного события);
+
* <code>hBEFORE</code> - execute before Main Event (for example can be used to stop execution of the Main Event if needed);
-
* <code>hAFTER</code> - выполняться после основного события (будут выполняться только если основное события успешно завешилось).
+
* <code>hAFTER</code> - execute after Main Event (this will executed only if Main Event has been successfully executed).
|-
|-
| {{ConfigProperty|Conditional|boolean}}
| {{ConfigProperty|Conditional|boolean}}
|
|
-
* ''<code>true</code>'' - выполняться только при наличии, в ''<code>$_REQUEST</code>'', данных от [[K4:Unit Configs#Prefix|префикса]] из опции [[#DoPrefix|DoPrefix]];
+
* ''<code>true</code>'' - execute ONLY if ''<code>$_REQUEST</code>'' contains data from [[K4:Unit Configs#Prefix|Unit prefix]] specified in  [[#DoPrefix|DoPrefix]] option (see below);
-
* ''<code>false</code>'' - выполняться всегда
+
* ''<code>false</code>'' - always execute
|-
|-
-
| {{ConfigProperty|HookToPrefix|string}} || Префикс, для которого создан hook.
+
| {{ConfigProperty|HookToPrefix|string}} || [[K4:Unit Configs#Prefix|Unit prefix]] we are hooking to.
|-
|-
-
| {{ConfigProperty|HookToSpecial|string}} || Special при котором будет срабатывать hook.
+
| {{ConfigProperty|HookToSpecial|string}} || Special of Unit prefix required for hook to be triggered.
|-
|-
-
| {{ConfigProperty|HookToEvent|array}} || Список [[K4:Events|событий]] с которыми данный hook будет связан (будет выполняться до или после них).
+
| {{ConfigProperty|HookToEvent|array}} || List of [[K4:Events|events]] which will trigger the hook (before or after their execution).
|-
|-
-
| {{ConfigProperty|DoPrefix|string}} || Префикс того [[K4:Unit Configs|unit config]], у которого будет выполняться hook (т.е. где он определён).
+
| {{ConfigProperty|DoPrefix|string}} || [[K4:Unit Configs#Prefix|Unit prefix]] where event triggered by the hook is defined.
|-
|-
-
| {{ConfigProperty|DoSpecial|string}} || Special, с которым вызывать событие из опции [[#DoEvent|DoEvent]].
+
| {{ConfigProperty|DoSpecial|string}} || Special of Unit prefix, that will be passed to triggered Event specified in [[#DoEvent|DoEvent]] option (see below).
|-
|-
-
| {{ConfigProperty|DoEvent|string}} || Событие, которое должно выполняться когда сработает hook.
+
| {{ConfigProperty|DoEvent|string}} || Event that will be triggered when the hooks is activated.
|}
|}
-
== Специальные значения опций ==  
+
== Special Value Options ==  
-
Для более гибкого (flexible) определения hook '''рекомендуется''' применять следующие специальные значения для опций при его объявлении:
+
For more flexibility it's recommended to define Hooks with the following special options:
-
* <code>'''HookToPrefix = '#PARENT#''''</code> - использовать значение ключа [[K4:Unit Configs#ParentPrefix|ParentPrefix]] текущего unit config;
+
* <code>'''HookToPrefix = '#PARENT#''''</code> - use current value of [[K4:Unit Configs#ParentPrefix|ParentPrefix]] key from the current Unit Configuration file;
-
* <code>'''HookToPrefix = '*''''</code> - любой префикс (т.е. выполняться для всех, зарегистрированных в системе префиксов), доступно с [[K4:Core v 5.0.0|Core v 5.0.0]];
+
* <code>'''HookToPrefix = '*''''</code> - any prefix (e.g., will execute for all prefixes registered in the system), available since [[K4:Core v 5.0.0|In-Portal v5.0.0]];
-
* <code>'''HookToSpecial = '*''''</code> - надо вызывать данный hook при любом Special у главного события;
+
* <code>'''HookToSpecial = '*''''</code> - call this hook with any Special from the Main Event;
-
* <code>'''DoPrefix = <nowiki>''</nowiki>'''</code> - событие из <code>DoEvent</code> ключа находится в [[EventHandler:About|обработчике событий]] заданном в текущем unit config;
+
* <code>'''DoPrefix = <nowiki>''</nowiki>'''</code> - the event from <code>DoEvent</code> key is located in [[EventHandler:About|Event Handler]] that is defined in current Unit Config file;
-
* <code>'''DoSpecial = '*'''' - использовать тот Special, с которым вызвано главное событие.
+
* <code>'''DoSpecial = '*'''' - use the same Special, that the Main Event was called with;
 +
 
 +
[[en:{{FULLPAGENAME}}]]
 +
[[ru:K4:Hooks]]
 +
 
 +
Translated from: [http://guide.in-portal.org/rus/index.php?title=K4:Hooks&oldid=397 revision 397]

Current revision

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

Hooks in In-Portal allow to execute any events before or after specific events in the system. A live example of this would be deleting a physical image from the file-system once data record of the image is deleted from the database. This functionality is implemented using "hooks".

Hook - is a an event which will be executed before or after the original event it's been hooked to by defining it in Hooks array in Unit Configuration File. There is no limit on number of hooks that can be setup for one event.

These are the terms that will be used in this article:

Current Unit Config - this a unit config where the Hook is defined Main Event - event which triggers the Hook

Decencies

  • hook should work strictly with the dataset of Unit it's been defined in or dataset of Main Event triggered the hook
  • hook and Main Event (which triggered the hook) should not be located in the same Event Handler (which means that HookToPrefix and DoPrefix can't the same)

Access to Main Event from inside the hooks can be done using the following code: 

$master_event =& $event->MasterEvent;

This will return a link to the object of the Main Event.

Registering a Hook

New Hooks can be registered (added) using the code below: 

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

All listed above keys are required. In case if hooks needs to be temporarily disabled then it's recommended to comment out it's entire definition and not only some parts of it (ie. DoEvent). All array keys starting with HookTo are related to definition of Main Event while all keys starting to Do describe which Event will be called once this hook triggered.

Option Name Description
Mode (int) When hook will executed in relation of the Main Event:
  • hBEFORE - execute before Main Event (for example can be used to stop execution of the Main Event if needed);
  • hAFTER - execute after Main Event (this will executed only if Main Event has been successfully executed).
Conditional (boolean)
  • true - execute ONLY if $_REQUEST contains data from Unit prefix specified in DoPrefix option (see below);
  • false - always execute
HookToPrefix (string) Unit prefix we are hooking to.
HookToSpecial (string) Special of Unit prefix required for hook to be triggered.
HookToEvent (array) List of events which will trigger the hook (before or after their execution).
DoPrefix (string) Unit prefix where event triggered by the hook is defined.
DoSpecial (string) Special of Unit prefix, that will be passed to triggered Event specified in DoEvent option (see below).
DoEvent (string) Event that will be triggered when the hooks is activated.

Special Value Options

For more flexibility it's recommended to define Hooks with the following special options:

  • HookToPrefix = '#PARENT#' - use current value of ParentPrefix key from the current Unit Configuration file;
  • HookToPrefix = '*' - any prefix (e.g., will execute for all prefixes registered in the system), available since In-Portal v5.0.0;
  • HookToSpecial = '*' - call this hook with any Special from the Main Event;
  • DoPrefix = '' - the event from DoEvent key is located in Event Handler that is defined in current Unit Config file;
  • DoSpecial = '*' - use the same Special, that the Main Event was called with;

Translated from: revision 397

Retrieved from "http://guide.in-portal.org/eng/index.php/K4:Hooks"