Custom Events

In addition to all of Mura's event hooks, developers may also create their own, custom event hooks. The main decision you'll want to make is whether you wish to "announce" an event, or "render" an event. Regardless of whether you choose to announce an event, or render an event, Mura will trigger your event as illustrated below, and in turn, any registered event handlers with these methods defined, will be executed:

on{YourEvent}

Announcing Events

When you "announce" an event, you're essentially sending a notification throughout Mura that something in particular is about to occur, or has just occurred. You may omit the "on" from your event name when announcing it. However, your method itself should contain the "on" prefix.

Syntax

The basic syntax for announcing an event is:

m.announceEvent('YourEvent', m);
// OR
m.announceEvent('onYourEvent', m);

When Mura encounters the code above, it will search for any registered event handlers to locate onYourEvent(), and if found, the method will be executed.

Example

The following example illustrates a very simple form, with a text field named myField. The value attribute will be pre-populated with its own value. In other words, since the event scope itself wraps CFML's URL, Form, and Request scopes, we can check the event scope for the value, and if the form is submitted, then any value entered will be used to pre-populate itself.

<form method="post">
  <input type="text" name="myField" value="[m]esapiEncode('html_attr', m.event('myField'))[/m]">
  <input type="hidden" name="myFormIsSubmitted" value="true">
  <input type="submit">
</form>

In the example form above, we're using a hidden field named myFormIsSubmitted with its value set to "true". By checking the event scope for this value, if found, we can trigger an event to occur, as shown the example below.

// check form submission via `onRenderStart`, and if found, announce your custom event.
public any function onRenderStart(m) {
  if ( arguments.m.event('myFormIsSubmitted') == 'true' ) {
  // announcing the event
  arguments.m.announceEvent('CustomFormSubmitted', arguments.m);
  }
}

If the form has been submitted, our customFormSubmitted event is announced, triggering any registered event handlers to execute.

public any function onCustomFormSubmitted(m) {
  // you could do whatever you want here
  // including dumping out the entire event itself to inspect it
  // or simply dumping out the value of a specific form filed
  // and then halt the rest of the process (for example only)
  WriteDump(var=arguments.m.event('myField'), abort=true);
}

Rendering Events

If you wish to "render" an event, in addition to sending a notification throughout Mura that something in particular is about to occur, or has just occurred, you are allowing for the possibility to render something to the browser. In other words, your code should be checking for a string to return, and if nothing is returned, then you'll most likely want to display something else by default.

Syntax

The basic syntax for rendering an event is:

m.renderEvent('YourEvent');

Examples

There are several ways you could choose to render event output. The following example illustrates a simple way to output the result of a rendered event.

<cfoutput>
#esapiEncode('html', m.renderEvent('YourEvent'))#
</cfoutput>

The example below is typical of how Mura renders events in its own code.

eventOutput = esapiEncode('html', m.renderEvent('YourEvent'));
if ( Len(eventOutput) ) {
WriteOutput(eventOutput);
} else {
// render something else / default output
}