Содержание
Система событий
Система событий позволяет добавлять пользовательские обработчики в дополнение или вместо стандартных в процессе работы любой части «Докувики», которая сообщает о своей активности через систему событий. Пользовательские обработчики, или хуки, могут быть добавлены в любой плагин, кода шаблона (темы) (или в саму «Докувики»). Action-плагины специально разработаны, чтобы получить преимущества системы событий. Они гарантированно загружаются на старте процесса и имеют возможность регистрироваться на получение определённых событий перед их появлением. Другие части «Докувики» могут не выполняться сразу или вообще в процессе работы для указанных страниц.
Также есть возможность создавать собственные события для пользовательского вики-контента.
Система событий состоит из трёх частей:
- объект «Событие»;
- основной обработчик события (контроллер). Это глобальный объект «Докувики» —
$EVENT_HANDLER
. Скрипт, который регистрирует события и обработчики. Когда событие появляется, он перебирает каждый хук (обработчик), зарегистрированный на это событие, передавая ему данные; - индивидуальные обработчики событий (хуки). Функции, которые ждут конкретное событие. Action является инструментом специально для таких функций, они также могут быть частью шаблонов, плагинов других типов или основного кода «Докувики».
Детальная информация описывающая существующие события и время их появления представлены в списке events list.
Объект «Событие»
class name Doku_Event
Объект «Событие» состоит из:
- Public свойства
name
, (readonly) хуки используют это для регистрации процесса конкретного событияdata
, (read/write) данные передаются в событие, хуки имеют возможность их проверять и изменятьresult
, (read/write) доступно после выполнения стандартных действий хуков, которые подписаны на пост-запросcanPreventDefault
, (readonly) флаг информирующий о возможности изменения действия по умолчанию
- Private свойства
_default
(boolean, по умолчаниюtrue
), указывает выполнится ли действие по умолчанию. Значение изменяется с помощью методаpreventDefault()
_continue
(boolean, по умолчаниюtrue
), указывает продолжать ли отправку события на хуки (приемники), которые уже приняли его. Значение изменяется с помощью методаstopPropagation()
.
- Public методы
trigger()
- автоматизация отправки событий. Этот метод принимает 2 опциональных параметра, имя функции действия по умолчанию (callback), и флаг возможности изменения этого действия (bool), возвращает результат события. Срабатывает после процесса генерации всех событий, отправляет сигнал «_BEFORE», выполняет действие по умолчанию, завершает работу сигналом «_AFTER».stopPropagation()
- останавливает дальнейшую генерацию событий, не предотвращает выполнение действий по умолчанию, которые начали свою работу.preventDefault()
- останавливает выполнение действия по умолчанию.
advise_*()
методы позволяют выполнить действия до или после действия по умолчанию (возможно, когда действия по умолчанию не подходят в данный момент времени).advise_before()
- принимает true/false параметр, который указывает, можно ли изменять действие по умолчанию, генерит сигнал «_BEFORE».advise_after()
- генерит сигнал «_AFTER».
Регистрация приёмников «события»
Для регистрации приёмника события нужно вызвать метод register_hook()
объекта $EVENT_HANDLER
. Action-плагин может сделать это через метод register()
своего контроллера $controller
. Другие части «Докувики» должны убедиться в своей доступности глобально или объявить $EVENT_HANDLER
как глобальную переменную:
global $EVENT_HANDLER; $EVENT_HANDLER->register_hook( ... )
О дополнительных параметрах функции register_hook() смотрите inc/events.php
.
Используйте register_hook($event, $advise, $obj, $method, $param=null, $seq=0)
с такими аргументами:
$event
string — имя используемое, событием;$advise
string —BEFORE
илиAFTER
, когда обработчик события должен сработать до или после;$obj
object — объект, в рамках которого должен выполняться этот метод. При значенииnull
метод становится глобально доступной функцией;$method
function — обработчик события. Больше информации на странице Event handlers (англ.).$param
mixed (необязательно) — данные, которые передаются в обработчик события. По умолчанию null;$seq
int (необязательно) — число, которое используются для контроля порядка выполнения обработчиков события. Хуки выполняются в соответствии порядка$seq
-номера. Если два или более хука имеют одинаковое значение$seq
, порядок их выполнения (относительно друг-друга) не определён. Хуки могут использовать-PHP_INT_MAX
илиPHP_INT_MAX
для обозначения себя первым или последним. Эти значения не дают гарантий быть первым/последним, если используются несколькими плагинами.
Генерация «события»
Событие может генерироваться тремя путями:
- самый простой — использовать функуцию
trigger_event()
. Она берёт все необходимые параметры для создания объекта события и генерирует его.
Используйтеtrigger_event($name, &$data, $action=null, $canPreventDefault=true)
с такими аргументами:$name
string — имя события;$data
mixed — данные события;$action
callback (необязательно) — имя функции действия по умолчанию (callback). По умолчанию null;$canPreventDefault
boolean (необязательно) — возможность хуку изменить действие по умолчанию. По умолчанию true;- return mixed — результат события в конце процесса его обработки. Это результат работы «действия по умолчанию». Также может изменяться обработчиком события после его сохранения в атрибут
result
объектаDoku_Event
, там где Doku_Event доступен своим обработчикам.trigger_event(<EVENT_NAME>, <event data>, <action callback>, <can prevent default>)
- управление процессом генерации события через advise_before($enablePreventDefault = true) и advise_after() объекта Doku_Event. Используйте эти методы, если действие по умолчанию невозможно описать в виде php-функции.
$evt = new Doku_Event(<EVENT_NAME>, <event data>); if ($evt->advise_before(<can prevent default>)) { // блок кода действий } $evt->advise_after(); unset($evt);
Примеры
(Это только примеры, которых может не быть в «Докувики.)
Сохранение страницы
// событие: 'IO_WIKIPAGE_SAVE' // данные: массив(имя файла, текст вики-страницы) // действие: сохранение исходников вики-страницы в файл. // результат: булево, страница сохранена $data = array($id,$wikitext); $ok = trigger_event('SAVE_WIKIPAGE', $data, io_savewikipage);
Возможны обработчики, индексаторы (indexers), переводчики (translators).
Дополнение/Замена ?do=... действий
// events: 'ACTION_ACT_PREPROCESS' & 'TPL_ACT_UNKNOWN' // data: $ACT (знчение переменной стринг-запроса ''do'') // action: ничего, обрабатывается скриптом генерации события // в ''inc/actions.php act_dispatch()'' $evt = new Doku_Event('ACTION_ACT_PREPROCESS', $ACT); if ($evt->advise_before()) { /* нормальное выполнение $ACT */ } $evt->advise_after(); unset($evt); // в ''inc/template.php tpl_content()'' default: /* неизвестное значение $ACT */ $evt = new Doku_Event('TPL_ACT_UNKNOWN', $ACT); if ($evt->advise_before()) { print "unknown action"; } $evt->advise_after(); unset($evt);
Возможны обработчики, пользовательские формы, дополнительные do
команды от UI-шаблона.
Завершение списка инструкций Обработчика
// event: ''PARSER_HANDLER_DONE'' // data: обработчик, включая список его инструкций завершения. // action: none // в ''inc/parser/handler.php _finalize() trigger_event('PARSER_HANDLER_DONE',$this);
доступны обработчики, плагины замены footnote, продвинутые обработчики контента.
Смотрите также
- Events List существующие события.
- Использование Action plugins для регистрации обработчиков событий.
- Больше о Event handlers
- Примеры event handlers code