Trying to output a variable that hasn't been defined will generate a Coldfusion error. When trying to output an argument from the event object that doesn't exist, the default returned value is an empty string. Understanding how, where and when event arguments are defined may be the most important part of learning Mach-II.

Populating the event object through XML.

This section uses the version 0 files including mach-ii.xml (a.k.a. mach-ii.00.xml).

Complex variables can be put into the event object via plugins, filters and listeners. Right now, we'll be dealing with simple string values which can most easily be defined in the configuration XML file using the <event-arg/> key.

view plain print about
1<event-handler event="home" access="public">
2    <event-arg name="pageTitle" value="Home" /><!-- easy, isn't it? -->
3    <view-page name="header" />
4    <view-page name="lhsMenu" contentArg="sidebar" />
5    <view-page name="homePage" contentArg="mainContent" />
6    <view-page name="template" />
7    <view-page name="footer" />
8</event-handler>

To output an event argument, call the function getArg() from the event object, passing in the argument's name. Open up the "header" page-view and you'll see some simple HTML and the placeholder for the pageTitle argument in the event object.

view plain print about
1<!--- /m2/views/layout/header.cfm --->
2<cfoutput>    
3    <title>Mach-II Primer: Contact Manager - #event.getArg("pageTitle")#</title>
4</cfoutput>

Both the home and exceptionEvent event-handlers include the "header" page-view. However, only the home event has defined the argument "pageTitle".

Definition of home:

view plain print about
1<event-handler event="home" access="public">
2    <event-arg name="pageTitle" value="Home" /><!-- easy, isn't it? -->
3    <view-page name="header" />
4    <view-page name="lhsMenu" contentArg="sidebar" />
5    <view-page name="homePage" contentArg="mainContent" />
6    <view-page name="template" />
7    <view-page name="footer" />
8</event-handler>

Final output for "header" in home:

view plain print about
1<title>Mach-II Primer: Contact Manager - Home</title>

Definition of exceptionEvent:

view plain print about
1<event-handler event="exceptionEvent" access="public">
2    <view-page name="header" />
3    <view-page name="exception" />
4    <view-page name="footer" />
5</event-handler>

Final output for "header" in exceptionEvent:

view plain print about
1<title>Mach-II Primer: Contact Manager - </title>

Page content as event arguments.

When the contentArg attribute is used in a <view-page />, the referenced <page-view/> is not placed in the file stack. Instead, it is compiled and its final output is placed into the event object. This file's content can now be used by any subsequent line (object) in the event definition.

In the home event, the page-views "lhsMenu" and "homePage" are converted into the event arguments "sideBar" and "mainContent" which are then referenced in the "template" page-view.

view plain print about
1<!--- /m2/views/layout/template.cfm --->
2<table width="770" cellspacing="0" cellpadding="4" align="center" border="0">
3    <tr>
4        <td id="sideNavigation">
5            <cfoutput>#event.getArg("sideBar")#</cfoutput>
6        </td>
7        <td id="mainContent">
8            <cfoutput><h3>#event.getArg("pageTitle")#</h3></cfoutput>
9            
10            <cfoutput>#event.getArg("mainContent")#</cfoutput>
11        </td>
12    </tr>
13</table>

Ordering event argument definitions.

The order in which you define event arguments matters. In home, had the event-arg "pageTitle" been defined after the view-page "header", the output for the title would have been the same as in exceptionEvent.

Here is how each piece of the event object sees the value of event arguments as home is compiled.

view plain print about
1<event-handler event="home" access="public">
2    <event-arg name="pageTitle" value="Home" />
3    <view-page name="header" />
4    <view-page name="lhsMenu" contentArg="sidebar" />
5    <view-page name="homePage" contentArg="mainContent" />
6    <view-page name="template" />
7    <view-page name="footer" />
8</event-handler>

EventView-pageReferencesReturns
homeheaderevent.getArg("pageTitle")Home
homeheaderevent.getArg("sidebar")[empty string]
homeheaderevent.getArg("mainContent")[empty string]
homelhsMenuevent.getArg("pageTitle")Home
homelhsMenuevent.getArg("sidebar")[empty string]
homelhsMenuevent.getArg("mainContent")[empty string]
homehomePageevent.getArg("pageTitle")Home
homehomePageevent.getArg("sidebar"){Contents of lhsMenu}
homehomePageevent.getArg("mainContent")[empty string]
hometemplateevent.getArg("pageTitle")Home
hometemplateevent.getArg("sidebar"){Contents of lhsMenu}
hometemplateevent.getArg("mainContent"){Contents of homepage}
homefooterevent.getArg("pageTitle")Home
homefooterevent.getArg("sidebar"){Contents of lhsMenu}
homefooterevent.getArg("mainContent"){Contents of homepage}

Final output for "header" in home:

view plain print about
1<title>Mach-II Primer: Contact Manager - Home</title>

Now let's change where we define the event-arg "pagetitle":

view plain print about
1<event-handler event="home" access="public">
2    <view-page name="header" />
3    <view-page name="lhsMenu" contentArg="sidebar" />
4    <view-page name="homePage" contentArg="mainContent" />
5    <event-arg name="pageTitle" value="Home" />
6    <view-page name="template" />
7    <view-page name="footer" />
8</event-handler>

EventView-pageReferencesReturns
homeheaderevent.getArg("pageTitle")[empty string]
homeheaderevent.getArg("sidebar")[empty string]
homeheaderevent.getArg("mainContent")[empty string]
homelhsMenuevent.getArg("pageTitle")[empty string]
homelhsMenuevent.getArg("sidebar")[empty string]
homelhsMenuevent.getArg("mainContent")[empty string]
homehomePageevent.getArg("pageTitle")[empty string]
homehomePageevent.getArg("sidebar"){Contents of lhsMenu}
homehomePageevent.getArg("mainContent")[empty string]
hometemplateevent.getArg("pageTitle")Home
hometemplateevent.getArg("sidebar"){Contents of lhsMenu}
hometemplateevent.getArg("mainContent"){Contents of homepage}
homefooterevent.getArg("pageTitle")Home
homefooterevent.getArg("sidebar"){Contents of lhsMenu}
homefooterevent.getArg("mainContent"){Contents of homepage}

Final output for "header" in home with "pageTitle" defined after "header":

view plain print about
1<title>Mach-II Primer: Contact Manager - </title>

One thing to note is that the line of XML that defines an event argument cannot also process or display the output for that event argument.

While we're currently only displaying content on the screen, the order of defining event arguments becomes much more important when we use the XML pass arguments to functions in order to process or return data. We'll revisit this again in the step covering Listeners.

Next Step

Now that you've got an idea of how pages and variables are defined in Mach-II, the next step is to start tearing apart the procedural code.