docs/package_pip_event-listener.md

   1 ---
   2 title: Event Listener Package Installation Plugin
   3 sidebar: sidebar
   4 permalink: package_pip_event-listener.html
   5 folder: package/pip
   6 parent: package_pip
   7 ---
   8
   9 Registers event listeners.
  10 An explanation of events and event listeners can be found [here](php_api_events.md).
  11
  12 ## Components
  13
  14 Each event listener is described as an `<eventlistener>` element with a `name` attribute.
  15 As the `name` attribute has only be introduced with WSC 3.0, it is not yet mandatory to allow backwards compatibility.
  16 If `name` is not given, the system automatically sets the name based on the id of the event listener in the database.
  17
  18 ### `<eventclassname>`
  19
  20 The event class name is the name of the class in which the event is fired.
  21
  22 ### `<eventname>`
  23
  24 The event name is the name given when the event is fired to identify different events within the same class.
  25 You can either give a single event name or a comma-separated list of event names in which case the event listener listens to all of the listed events.
  26
  27 ### `<listenerclassname>`
  28
  29 The listener class name is the name of the class which is triggered if the relevant event is fired.
  30 The PHP class has to implement the `wcf\system\event\listener\IParameterizedEventListener` interface.
  31
  32 {% include callout.html content="Legacy event listeners are only required to implement the deprecated `wcf\system\event\IEventListener` interface. When writing new code or update existing code, you should always implement the `wcf\system\event\listener\IParameterizedEventListener` interface!" type="warning" %}
  33
  34 ### `<inherit>`
  35
  36 The inherit value can either be `0` (default value if the element is omitted) or `1` and determines if the event listener is also triggered for child classes of the given event class name.
  37 This is the case if `1` is used as the value.
  38
  39 ### `<environment>`
  40
  41 The value of the environment element must be one of `user`, `admin` or `all` and defaults to `user` if no value is given.
  42 The value determines if the event listener will be executed in the frontend (`user`), the backend (`admin`) or both (`all`).
  43
  44 ### `<nice>`
  45
  46 The nice value element can contain an integer value out of the interval `[-128,127]` with `0` being the default value if the element is omitted.
  47 The nice value determines the execution order of event listeners.
  48 Event listeners with smaller nice values are executed first.
  49 If the nice value of two event listeners is equal, they are sorted by the listener class name.
  50
  51 {% include callout.html content="If you pass a value out of the mentioned interval, the value will be adjusted to the closest value in the interval." type="info" %}
  52
  53 ### `<options>`
  54
  55 The options element can contain a comma-separated list of options of which at least one needs to be enabled for the event listener to be executed.
  56
  57 ### `<permissions>`
  58
  59 The permissions element can contain a comma-separated list of permissions of which the active user needs to have at least one for the event listener to be executed.
  60
  61
  62 ## Example
  63
  64 ```xml
  65 <?xml version="1.0" encoding="UTF-8"?>
  66 <data xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/2019/eventListener.xsd">
  67         <import>
  68                 <eventlistener name="inheritedAdminExample">
  69                         <eventclassname>wcf\acp\form\UserAddForm</eventclassname>
  70                         <eventname>assignVariables,readFormParameters,save,validate</eventname>
  71                         <listenerclassname>wcf\system\event\listener\InheritedAdminExampleListener</listenerclassname>
  72                         <inherit>1</inherit>
  73                         <environment>admin</environment>
  74                 </eventlistener>
  75
  76                 <eventlistener name="nonInheritedUserExample">
  77                         <eventclassname>wcf\form\SettingsForm</eventclassname>
  78                         <eventname>assignVariables</eventname>
  79                         <listenerclassname>wcf\system\event\listener\NonInheritedUserExampleListener</listenerclassname>
  80                 </eventlistener>
  81         </import>
  82
  83         <delete>
  84                 <eventlistener name="oldEventListenerName" />
  85         </delete>
  86 </data>
  87
  88 ```