Events and Listeners

An event is a point in a module's code where it lets other modules join in. The module fires the event with some data; every module listening for it gets the data, can change it, and returns it. The firing module then uses what comes back.

So modules extend each other without changing each other's code. For example, the Editor Embedded Media module fires an event when it builds its dialog, and each media module adds its own tab.

Register a listener in your _init():

jrCore_register_event_listener('jrUser', 'signup_activated', 'xxFoo_signup_activated_listener');

And write the function, with these five arguments:

function xxFoo_signup_activated_listener($_data, $_user, $_conf, $_args, $event)
{
    // $_data  - the data the event sent; change it if you need to
    // $_user  - the current user
    // $_conf  - the settings
    // $_args  - extra information from the module firing the event
    // $event  - the event's name
    return $_data;
}

The naming convention is (your module)_(event)_listener.

Register the event in _init(), with a description:

jrCore_register_event_trigger('xxFoo', 'foo_created', 'Fired when a new foo is created');

Then fire it where other modules may want to act:

$_data = jrCore_trigger_event('xxFoo', 'foo_created', $_data, array('foo_id' => $id));

The fourth argument becomes the listeners' $_args.

Turn on Run in Developer Mode in Developer Tools. Each module's Info tab then lists the events it fires, with their descriptions, and which modules listen to them. Read a listener of the same event in another module to see what $_data contains, or write it to the Debug Log with fdebug($_data).

Some events everyone uses: jrCore fires daily_maintenance, hourly_maintenance and minute_maintenance (see Maintenance Events), db_create_item and db_update_item around item changes, and form_display when a form is shown.