Primer Part 2: Variables vs. Arguments

Table of Contents

1. Populating the event object through XML
2. Other Chapters

Trying to output a variable that hasn't been defined will generate a CFML 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 an#### Table of Contents

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-handler event="home" access="public">
        <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.

    <!--- /m2/views/layout/header.cfm --->
    <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-handler event="home" access="public">
        <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:

    <title>Mach-II Primer: Contact Manager - Home</title>

Definition of exceptionEvent:

    <event-handler event="exceptionEvent" access="public">
        <view-page name="header" />
        <view-page name="exception" />
        <view-page name="footer" />
    </event-handler>

Final output for "header" in exceptionEvent:

    <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.

    <!--- /m2/views/layout/template.cfm --->
    <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-handler event="home" access="public">
        <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:

<title>Mach-II Primer: Contact Manager - Home</title>

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

<event-handler event="home" access="public">
   <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":

    <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.

Other Chapters

• Mach-II Primer Series Navigation
• Part 1 - Files versus Events
• Part 2 - Variables versus Arguments
• Part 3 - Flip This Code
• Part 4 - Using Gateways to manage record sets
• Part 5 - Mediating events with Listeners
• Part 6 - Getting the details with Beans and DAOs
• Part 7 - Processing data with Beans and DAOs using Event-Filters

Special thanks to Adrian J. Moreno of IKnowKungFoo for contributing this series of primers.