Mach-II Primer : 2 : Variables vs. Arguments
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.
<event-arg name="pageTitle" value="Home" /><!-- easy, isn't it? -->
<view-page name="header" />
<view-page name="lhsMenu" contentArg="sidebar" />
<view-page name="homePage" contentArg="mainContent" />
<view-page name="template" />
<view-page name="footer" />
</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.
<cfoutput>
<title>Mach-II Primer: Contact Manager - #event.getArg("pageTitle")#</title>
</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:
<event-arg name="pageTitle" value="Home" /><!-- easy, isn't it? -->
<view-page name="header" />
<view-page name="lhsMenu" contentArg="sidebar" />
<view-page name="homePage" contentArg="mainContent" />
<view-page name="template" />
<view-page name="footer" />
</event-handler>
Final output for "header" in home:
Definition of exceptionEvent:
<view-page name="header" />
<view-page name="exception" />
<view-page name="footer" />
</event-handler>
Final output for "header" in exceptionEvent:
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.
<table width="770" cellspacing="0" cellpadding="4" align="center" border="0">
<tr>
<td id="sideNavigation">
<cfoutput>#event.getArg("sideBar")#</cfoutput>
</td>
<td id="mainContent">
<cfoutput><h3>#event.getArg("pageTitle")#</h3></cfoutput>
<cfoutput>#event.getArg("mainContent")#</cfoutput>
</td>
</tr>
</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.
<event-arg name="pageTitle" value="Home" />
<view-page name="header" />
<view-page name="lhsMenu" contentArg="sidebar" />
<view-page name="homePage" contentArg="mainContent" />
<view-page name="template" />
<view-page name="footer" />
</event-handler>
Event View-page References Returns home header event.getArg("pageTitle") Home home header event.getArg("sidebar") [empty string] home header event.getArg("mainContent") [empty string] home lhsMenu event.getArg("pageTitle") Home home lhsMenu event.getArg("sidebar") [empty string] home lhsMenu event.getArg("mainContent") [empty string] home homePage event.getArg("pageTitle") Home home homePage event.getArg("sidebar") {Contents of lhsMenu} home homePage event.getArg("mainContent") [empty string] home template event.getArg("pageTitle") Home home template event.getArg("sidebar") {Contents of lhsMenu} home template event.getArg("mainContent") {Contents of homepage} home footer event.getArg("pageTitle") Home home footer event.getArg("sidebar") {Contents of lhsMenu} home footer event.getArg("mainContent") {Contents of homepage}
Final output for "header" in home:
Now let's change where we define the event-arg "pagetitle":
<view-page name="header" />
<view-page name="lhsMenu" contentArg="sidebar" />
<view-page name="homePage" contentArg="mainContent" />
<event-arg name="pageTitle" value="Home" />
<view-page name="template" />
<view-page name="footer" />
</event-handler>
Event View-page References Returns home header event.getArg("pageTitle") [empty string] home header event.getArg("sidebar") [empty string] home header event.getArg("mainContent") [empty string] home lhsMenu event.getArg("pageTitle") [empty string] home lhsMenu event.getArg("sidebar") [empty string] home lhsMenu event.getArg("mainContent") [empty string] home homePage event.getArg("pageTitle") [empty string] home homePage event.getArg("sidebar") {Contents of lhsMenu} home homePage event.getArg("mainContent") [empty string] home template event.getArg("pageTitle") Home home template event.getArg("sidebar") {Contents of lhsMenu} home template event.getArg("mainContent") {Contents of homepage} home footer event.getArg("pageTitle") Home home footer event.getArg("sidebar") {Contents of lhsMenu} home footer event.getArg("mainContent") {Contents of homepage}
Final output for "header" in home with "pageTitle" defined after "header":
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.
By "pageContent" do you mean "mainContent" (in the Page content as event arguments section)?
Yes, and thanks for catching that.
