System Events

Last updated Jan 27th, 2022 | Page history | Improve this page | Report an issue

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$306 per month—let's make that $500!

Learn more

What are System Events?¶

System Events are the events in MODX that Plugins are registered to. They are 'fired' throughout the MODX code, allowing Plugins to interact with MODX code and add custom functionality without hacking core code.

The Model of a System Event¶

The system events table is found under {table_prefix}_system_eventnames, and has the following fields:

id - The unique ID of the event.
name - The name of the event. This is how they are referenced in code, via the modX.invokeEvent method.
service - What type of system event this event is.
groupname - Used for user interfaces, primarily for filtering, grouping and sorting of events. Not used explicitly in the modx model.

Service Types¶

The 'service' field in the System event is a number; the numbers reference different types of System Events. They are:

1 - Parser Service Events
2 - Manager Access Events
3 - Web Access Service Events
4 - Cache Service Events
5 - Template Service Events
6 - User Defined Events

3 is not fired in the 'mgr' context; 2 is not fired in any context but 'mgr'.

Available Events¶

This is not an exhaustive list as events are still being documented. Thank you for your patience. The TV, Template and Snippet events are still to be documented. For a complete list, please either view a Plugin in the manager and see the System Events tab, or view here. Note also that all WUsr (web-user) events have been removed.

Custom Events¶

You can create your own custom events, but there is currently no GUI available for this; instead you must use the API. Events have the following attributes:

name - the unique event name.
service - loose attempt to group events for particular areas. 1,2,4,5,6 are loaded inside the manager, whereas 1,3,4,5,6 are loaded outside the manager. (see getEventMap())
groupname - Used for visually grouping the events in the MODX manager (visible as a Plugin tab).

Creating an event using the MODX API would look something like this:

$Event = $modx->newObject('modEvent');
$Event->set('name', 'OnMyCustomEvent');
$Event->set('service',1);
$Event->set('groupname', 'Custom');

Then your code could trigger that event by name:

$modx->invokeEvent('OnMyCustomEvent', $options);

Finally, a plugin could be set to listen for that event. In this case, it can receive options passed to it.

//... TODO...