Custom Events - Mura Docs v6

Custom Events

In addition to defined methods in your Site eventHandler.cfc, you can add custom methods and events with the pluginManager.addEventHandler() method. This can be extremely useful when building Mura plugins.

pluginManager.addEventHandler(
[component instance]
, '{SiteID}'
);
pluginManager.addEventHandler(
'[component path]'
, '{SiteID}'
, [persist {true | false}]
);

Site eventHandler.cfc

Every site in Mura has its own eventHandler.cfc where you can define event handling methods without needing to bind it to an actual plugin.

You can find this file at: /{SiteID}/includes/eventHandler.cfc

Since the Site eventHandler.cfc is a single file and is instantiated on every request, if you need to define a large number of events (or if you need your handler to persist between requests), you could run into problems. The pluginManager.addEventHandler() method solves this issue.

Theme eventHandler.cfc

You can also place an eventHandler.cfc into the root your theme directory:

/{SiteID}/includes/themes/{themeName}/eventHandler.cfc

The major difference between the Theme eventHandler.cfc and a Site eventHandler.cfc is that this component will only be instantiated and registered during Mura's onApplicationLoad event. So, any changes made to it will not take until the application has been reloaded.

Creating a Custom Event Handler

Below is an example of a custom event handler. You could place this anywhere within your site. 

For example: /{SiteID}/includes/themes/{themeName}/exampleHandler.cfc

component output='false' extends='mura.cfobject' {
variables.pageHits = 0;
public any function onAddHit($) {
variables.pageHits++;
$.event(
'pageHits'
, 'Total Hits: ' & variables.pageHits
);
}

Note that Mura uses on{Name}, onGlobal{Name} and standard{Name} for binding events.

Loading a Custom Event Handler

Below is an example of how to use the onApplicationLoad() event to instantiate the custom handler and register it with the pluginManager using the Site eventHandler.cfc located at:
/{SiteID}/includes/eventHandler.cfc

component output='false' extends='mura.cfobject' {
public any function onApplicationLoad($) {
var myCustomHandler = new exampleHandler();
$.getBean('pluginManager').addEventHandler(
myCustomHandler, $.event('SiteID')
);
}
}

This assumes there is a file called exampleHandler.cfc located in the same directory as the Site eventHandler.cfc.

Announcing an Event

The basic syntax for announcing an event in Mura is:

$.announceEvent('yourCustomEvent');

The code above will trigger any of the following defined events to execute:

onYourCustomEvent()
onGlobalYourCustomEvent()
standardYourCustomEvent()

The code to announce an event can be placed in any number of places within your code. For example, if you want to announce the addHit event anytime a page titled "Announcing Events" is requested, you could add something like the following to your exampleHandler.cfc file:

public void function onRenderStart($) {
if ( $.content('title') == 'Announcing Events' ) {
$.announceEvent('addHit');
}
}

To view the total page hits, the following code could be placed in the Body area of a page titled "Announcing Events":

Total Page Hits: [mura]$.event('pageHits')[/mura]

The above code assumes you are placing it inside the HTMLEditor area since it is using the [mura] tags.