Nucleus Plugins can subscribe to events that occur whenever something important happens. The plugin can then execute some actions, or output some text.

Example

Below is an example of how a plugin subscribes to the PreAddComment-event, an event that is generated immediately before a comment is added to a blog.

class NP_Acronyms extends NucleusPlugin {
  ...
  function getEventList() { return array('PreAddComment'); }
  ...
  function event_PreAddComment(&$data) {
    // replace acronym HTML
    $data['comment']['body'] =
        strreplace('HTML',
                   '<acronym title="HyperText Markup Language">HTML</acronym>',
                   $data['comment']['body']);
  }
}

This plugin replaces the text HTML in each comment by the text <acronym title="HyperText Markup Language">HTML</acronym>. The acronym-tag is a HTML-tag that allows authors to provide extra information on acronyms.

Subscribing to events

Here's the steps you need to take to subscribe to an event:

1. Add the event name to the array returned by the getEventList-method
2. Create a method with signature event_EventName($data), in which the handling of the event is done

Multiple plugins can subscribe to the same event. The order in which these plugins are notified is the same order as the ordening in the plugin list of the admin area. Plugins higher in the list get notified earlier on.

Parameters

The event_EventName-method gets only one parameter, $data, of which the contents differs depending on the event. It is an associative array with data. Objects and arrays that are passed in this array, are passed by reference, so the changes you make there will be remembered.

The event list below uses some colors to indicate if changes in the parameters will be seen by nucleus or not:

• pass-by-reference: when changes are made to this kind of parameters, they will be seen by Nucleus.
• pass-by-value: a copy of the value is made before it is sent to the plugin event handler. Changes in the contents of these variables will be discarded automatically.

Objects that are passed as parameters are indicates as follows: object. Most objects are also passed by reference, making them look like object by ref