docs/package/pip/template-listener.md

   1 # Template Listener Package Installation Plugin
   2
   3 Registers template listeners.
   4 Template listeners supplement [event listeners](event-listener.md), which modify server side behaviour, by adding additional template code to display additional elements.
   5 The added template code behaves as if it was part of the original template (i.e. it has access to all local variables).
   6
   7 ## Components
   8
   9 Each event listener is described as an `<templatelistener>` element with a `name` attribute.
  10 As the `name` attribute has only be introduced with WSC 3.0, it is not yet mandatory to allow backwards compatibility.
  11 If `name` is not given, the system automatically sets the name based on the id of the event listener in the database.
  12
  13 ### `<templatename>`
  14
  15 The template name is the name of the template in which the event is fired. It correspondes to the `eventclassname` field of event listeners.
  16
  17 ### `<eventname>`
  18
  19 The event name is the name given when the event is fired to identify different events within the same template.
  20
  21 ### `<templatecode>`
  22
  23 The given template code is literally copied into the target template during compile time.
  24 The original template is not modified.
  25 If multiple template listeners listen to a single event their output is concatenated using the line feed character (`\n`, U+000A) in the order defined by the [`niceValue`](#niceValue).
  26
  27 !!! warning "It is recommend that the only code is an `{include}` of a template to enable changes by the administrator. Names of templates included by a template listener start with two underscores by convention."
  28
  29 ### `<environment>`
  30
  31 The value of the environment element can either be `admin` or `user` and is `user` if no value is given.
  32 The value determines if the template listener will be executed in the frontend (`user`) or the backend (`admin`).
  33
  34 ### `<nice>`
  35
  36 <span class="label label-info">Optional</span>
  37
  38 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.
  39 The nice value determines the execution order of template listeners.
  40 Template listeners with smaller nice values are executed first.
  41 If the nice value of two template listeners is equal, the order is undefined.
  42
  43 !!! info "If you pass a value out of the mentioned interval, the value will be adjusted to the closest value in the interval."
  44
  45 ### `<options>`
  46
  47 <span class="label label-info">Optional</span>
  48
  49 The options element can contain a comma-separated list of options of which at least one needs to be enabled for the template listener to be executed.
  50
  51 ### `<permissions>`
  52
  53 <span class="label label-info">Optional</span>
  54
  55 The permissions element can contain a comma-separated list of permissions of which the active user needs to have at least one for the template listener to be executed.
  56
  57 ## Example
  58
  59 {jinja{ codebox(
  60   title="templateListener.xml",
  61   language="xml",
  62   filepath="package/pip/templateListener.xml"
  63 ) }}