Система событий позволяет добавлять пользовательские обработчики в дополнение или вместо стандартных в процессе работы любой части «Докувики», которая сообщает о своей активности через систему событий. Пользовательские обработчики, или хуки, могут быть добавлены в любой плагин, кода шаблона (темы) (или в саму «Докувики»). 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 для обозначения себя первым или последним. Эти значения не дают гарантий быть первым/последним, если используются несколькими плагинами.

Событие может генерироваться тремя путями:

1. самый простой — использовать функуцию 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>) 

2. использование метода trigger(). Не рекомендуется к использованию; желательно применять функцию trigger_event(), указанную выше.

   $evt = new Doku_Event(<EVENT_NAME>,<event_data>);
   $evt->trigger(<default action>,<can prevent default>);
   unset($evt);

3. управление процессом генерации события через 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).

// 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