Event Handlers

Mura event handlers are simply ColdFusion components (CFCs), or files saved with the extension .cfc. Mura event handlers contain methods/functions, and may contain other variables and/or data. Most Mura event handlers will contain one or more of Mura's event hooks, and/or custom event hooks.

The event hooks are merely "announced" during specific points of a request. Registered event handlers will be parsed when the event they're registered for occurs, and if any event hooks are found, they will be executed. For example, if you have two registered even handlers, and both of them contain a method listening for the same event hook, both methods will execute, whenever the event is announced.

As described in the Standard Events section, Mura's standard events handler is located under {context}/requirements/mura/Handler/standardEventsHandler.cfc. The methods may be viewed via Mura's Component API at http://www.getmura.com/component-api/7.0/index.html?mura/Handler/standardEventsHandler.html.

You may also have several Mura event handlers throughout your sites, themes, content types, display objects, and plugins. In addition, you can choose to register your event handlers by convention, or explicitly register them via a known event handler. Both options are described below.

Example Event Handler

With the exception of the "Site" event handler, or the "Theme" event handler, you can name your event handler anything you want, as long as it has the .cfc file extension. All event handlers should extend mura.cfobject. By doing so, you allow yourself the ability to leverage many of Mura's baked-in methods and functionality for working with Mura objects.

CFScript-based .CFC Example

component extends="mura.cfobject" {
public any function onSomeEvent(m) {
// Do something
}
}

Tag-based .CFC Example

<cfcomponent extends="mura.cfobject" output="false">
<cffunction name="onSomeEvent" access="public" returntype="any">
  <cfargument name="m" hint="Mura Scope">
<!--- Do something --->
  </cffunction>
</cfcomponent>

How to Register Event Handlers by Convention

One way to register a Mura event handler is by convention. This means, if you create a .CFC file, and place it in a "known" location, Mura will automatically register it, and any event hooks contained within it will be executed when announced.

The "Site" Event Handler

Mura automatically checks every site for a specific file, labeled eventHandler.cfc,under the following location:

{context}/{SiteID}/includes/eventHandler.cfc

If this file is found, Mura will instantiate it on every front-end request. This means that any methods placed within this file should be specific to front-end requests. If you attempt to add any other request types here, for example, any events which occur only during the admin request lifecycle, they will not be executed.

The "Theme" Event Handler

Mura automatically checks the theme for a specific file, labeled eventHandler.cfc, under the following location:

{context}/{SiteID}/includes/themes/{ThemeName}/eventHandler.cfc

Mura checks for this file during the onApplicationLoad event. When discovered, Mura then instantiates it, and places the file into the application scope.

Note: Since the file is only instantiated when the application loads, you must reload Mura anytime you make a change to the file itself.

Content Type & Display Object Event Handlers

Mura automatically scans both the content_types and display_objects directories for the following directory structure:

../model/handlers/{anyFilename}.cfc

Any .cfc discovered under these ../model/handlers/ directories will be registered as event handlers. Currently, content_types and display_objects directories can reside under a site and/or a theme.

{context}/{SiteID}/includes/content_types/model/handlers/
{context}/{SiteID}/includes/display_objects/model/handlers/
{context}/{SiteID}/includes/themes/{ThemeName}/content_types/model/handlers/
{context}/{SiteID}/includes/themes/{ThemeName}/display_objects/model/handlers/

Additional information regarding content types and display objects can be found in the Mura Rendering section.

How to Explicitly Register Event Handlers

The basic syntax for explicitly registering a custom event handler is:

m.getBean('pluginManager').addEventHandler(
  {handlerObject or path}
  , {SiteID}
);

For example, you may use one of the "known" registered event handlers, such as either the "Site" or "Theme" event handler. Then, using the onApplicationLoad event, you can register your custom event handler as follows:

public any function onApplicationLoad(event, m) {
// The customHandler.cfc file exists in the same directory as this file
var myHandler = new customHandler();
  // Register the custom handler
arguments.m.getBean('pluginManager').addEventHandler(
  myHandler
  , arguments.event.get('siteid')
);
}

Plugin Event Handlers

Plugin event handlers should extend mura.plugin.pluginGenericEventHandler, instead of using the typical mura.cfobject. Doing so allows you access to the plugin's own configuration information via variables.pluginConfig, as well as Mura's configuration data via variables.configBean.

Registering event handlers in plugins is covered in the Plugins section.