XML Configuration File Quick Reference

Introduction
The Importance of Being Valid - Use the DTD
Tag Overview
Commands
Properties
- array
- element
- key
- property
  - Property Type Shortcuts
- properties
- struct
- value
Plugins & Filters
Listeners
- listener
- listeners
Event-Handlers
- event-handler
- event-handlers
Includes & Modules
Message-Subscribers
Views
Subroutines
- subroutine
- subroutines
General

Introduction

Since its inception, part of the core mission of team Mach-II and the Mach-II framework has been to promote the development of flexible, powerful, and easily maintainable CFML applications. A significant part of the architecture which has made these goals reality is the mach-ii.xml configuration file, which serves as a centralized location to control application flow and behavior.

The purpose of this document is to outline each of the available commands in the mach-ii.xml file, and to offer both a quick overview for new Mach-II developers, as well as a reference for existing developers.

This document was written against Mach-II 1.6. Tags and attributes that apply to higher versions are noted.

The Importance of Being Valid - Use the DTD

Mach-II comes bundled with a DTD file so you can validate your XML configuration files against the official known schema. This is extremely beneficial to developers because you can get instant feedback on if you are using the right attributes in a command or cannot remember an acceptable value for something like the statusType attribute in the redirect command.

Another important reason is there can be some un-intended behavior if certain things are not configured correctly. A notable example is the alias attribute in the cache command whereas the cache-clear command uses an aliases attribute. We support clearing multiple elements from a cache at once whereas it is only possible (and clearly logical) that the cache command is dealing with a single block. A misconfiguration of the cache-clear command using the singular alias attribute (which is incorrect and will cause a malformed XML configuration file) will cause the entire cache to be cleared instead of a single element as the developer is trying to do.

So if you will indulge us being on our soapbox a little longer, take our advice and add in a <DOCTYPE> declaration to your XML configuration files and use the DTD with your XML editor (simple text editors like notepad do not support DTD validation so this is another excuse to use real XML editor). If you don't know how to add in the doctype, see our handy FAQ on Using the DTD.

Tag Overview

Element	Attributes	Description
announce	event, module, [copyEventArgs]	from within an event handler, adds a new event to the event queue for processing
array		builds an array via xml
cache	[id, aliases, strategyName, criteria]	caches data and output nested inside the tag
cache-clear	[ids, aliases, strategyNames, criteria, condition]	clears a cache by id(s), alias(es) or strategy names by condition and/or criteria
call-method	bean, method, [args, resultArg]	calls a method in the service layer and optionally put the result in a event argument (1.8+)
element	value	defines a value for an element in an xml built array
event-filter	name, type, [mapping, overrideAction]	registers an event-filter CFC for use throughout the configuration file
event-filters		parent node to one or more event-filter nodes
event-handler	event, access, [mapping, overrideAction, secure]	defines the commands necessary to handle any event in the application
event-handlers	[secureDefault]	parent node to one or more event-handler nodes
event-arg	name, value, [variable], [overwrite]	sets an argument in the current event being handled
event-bean		creates a bean in the event and populate the bean with properties from the event
event-mapping	event, mapping, [mappingModule]	maps the announcement of an event to another event name
execute		executes a subroutine
filter	name	runs an event-filter
include	file	introduced in 1.5, includes an additional Mach-II configuration file
includes		parent node to one or more include nodes
key	name, [value]	defines a name/value pair in an xml built struct
listener	name, type, [mapping, overrideAction]	registers a listener CFC to be referenced throughout the configuration file
listeners		parent node to one or more listener nodes
mach-ii	version	root node of any Mach-II configuration file
message	name	defines the message to be referenced throughout the configuration file
message-subscribers		parent node to one or more message nodes
module	name, extends, file, mapping	defines one or more pier or sub-applications to be used within the context of the current applicationv
modules	basename	parent node to one or more module nodes
notify	listener, method, [resultArg]	calls a method from one listener registered in the listeners section of the configuration file
page-view	name, page, [overrideAction, mapping, useParentAppRoot]	registers a .cfm template for use throughout the configuration file
page-views		parent node to one or more page-view nodes
parameter		sends custom parameters to controller layer objects (Filters, Plugins, Listeners, Properties) for use within the CFC
parameters		parent node to one or more parameter nodes
plugin	name, type, [mapping, overrideAction]	registers a plugin CFC to be processed by Mach-II at each of nine request plugin points
plugins	[runParent]	parent node to one or more plugin nodes
property	name, type, [mapping, overrideAction, value]	defines an property (variable) to be used throughout the application
properties		parent node to one or more property nodes
publish	message	from within an event handler, publishes a message which typically executes a calls to or more listener objects
redirect	event, [module, url, args, persist, persistArgs, persistArgsIngore, statusType]	redirect the request a new event
struct		builds a struct via xml
subroutine	name, [mapping, overrideAction]	defines a series of Mach-II configuration commands to be executed inline
subroutines		parent node to one or more subroutine nodes
subscriber	listener, method, contentArg	defines a listener and method as a subscriber to a particular message
value		specifies the value of an array element or struct key
view-loader	type	specifies a view-load that loads view by convention over configuration (1.8+)
view-page	name, [contentArg, append, prepend]	specifies a page-view to display

Tag Detail

Commands

announce

The <announce> command is called from within an <event-handler> node, and adds a new event to the event queue for processing.

Attribute	Values	Required	Default	Description
event	name of event	required		specifies which event to announce
module	name of module	optional		specifies the module which the event is in
copyEventArgs	true,false	optional	true	specifies whether current event args should be copied into the announced event

    <event-handler>
        <notify listener="myListener" method="myMethod" resultArg="myResult" />
        <event-arg name="myArgName" value="myArgValue" />
        <announce event="someOtherEvent" copyEventArgs="true" />
    </event-handler>

cache

Attribute	Values	Required	Default	Description
id	unique id	optional		Unique id this cache block is to be known by
aliases	list of aliases	optional		List of aliases this cache can be reference by later on such as clearing the cache.
strategyName	name of cache strategy to use	optional		The name of the cache strategy you wish to use as specified in the parameter for the Caching property. If left out, defaultCacheName will be used.
criteria		optional	true	Comma delimited list of optional criteria to further identify the storage of your data. See below for more information.

    <event-handler name="home" access="public">
        <cache>
            <view-page name="home" />
        </cache>
    </event-handler>

The <cache> command only caches data that is located in the event that:

has been added to the event by a command or other code inside the <cache> block
was changed by a command or other code inside the <cache> block

The <cache> command does not cache data that:

was set to the event or existed in the event before the <cache> block was executed
does not exist in the event such a scope like the request scope (this affects users of the deprecated resultKey and contentKey features)

cache-clear

Attribute	Values	Required	Default	Description
ids	unique ids	optional		List of unique ids to clear (can be a Mach-II expression that resolves to a list or array - Mach-II 1.8+)
aliases	list of aliases	optional		List of aliases to clear (can be a Mach-II expression that resolves to a list or array - Mach-II 1.8+)
strategyNames	list of cache strategy names	optional		A list of the cache strategies you wish to clear as specified in the parameter for the Caching property. If left out, defaultCacheName will be used.
criteria		optional		Comma delimited list of optional criteria to further identify which items in the cache you want to clear. See below for more information.
condition	expression	optional	true	A expression that must be met in order for the cache to be cleared.

A few attribute names differ from the attributes available in the cache command. Those attributes are aliases, ids and strategyNames which are all plural however in the cache command they are singular. This is because cache-clear support clearing multiple aliases, id or cache strategies by name at once. Please beware of these differences as leaving of aliases or ids when trying to clear a specific element will essentially clear the entire cache because no aliases or ids were specified.

The cache-clear command also accepts the strategyNames attribute, so an entire caching strategy may be cleared programmatically in one command. You can also specify the ids, aliases and criteria attributes so that you clear out a specific items in the cache. Here is an example event-handler with cache-clear:

Clears cache blocks by alias acctNav where the criteria is user_id key is value returned from an event arg named userId:

    <event-handler event="logout">
        <cache-clear aliases="acctNav" criteria="user_Id=${event.userId}" />
        <notify listener="AccountListener" method="logoutUser" />
        <announce event="home" copyEventArgs="true" />
    </event-handler>

Clears an entire cache strategy by name of general:

    <event-handler event="logout">
        <cache-clear strategyNames="general" />
        <notify listener="AccountListener" method="logoutUser" />
        <announce event="home" copyEventArgs="true" />
    </event-handler>

Clears a cache block with id of home when the condition evaluates to true:

    <event-handler event="logout">
        <cache-clear ids="home" condition="${event.someArg} EQ 1" />
        <notify listener="AccountListener" method="logoutUser" />
        <announce event="home" copyEventArgs="true" />
    </event-handler>

Clears the entire default cache strategy:

    <event-handler event="logout">
        <cache-clear />
        <notify listener="AccountListener" method="logoutUser" />
        <announce event="home" copyEventArgs="true" />
    </event-handler>

Using an expression to dynamically indicate the ids to clear (1.8+). Must resolve to an array or comma delimited list (event.clearIds):

    <event-handler event="logout">
        <cache-clear ids="home" ids="${event.clearIds}" />
        <notify listener="AccountListener" method="logoutUser" />
        <announce event="home" copyEventArgs="true" />
    </event-handler>

Using an expression to dynamically indicate the aliases to clear (1.8+). Must resolve to an array or comma delimited list (event.clearAliases):

    <event-handler event="logout">
        <cache-clear ids="home" aliases="${event.clearAliases}" />
        <notify listener="AccountListener" method="logoutUser" />
        <announce event="home" copyEventArgs="true" />
    </event-handler>

criterion

In Mach-II Simplicity (1.8), you can specify a collection (list or array) for a single criterion. This allows you to loop over a list or array of criterion so you it is possible to clear multiple caches based of a criteria. If you want to use a collection for a single criterion, you must use nested <criterion> tags and you cannot combine nested tags with the criteria attributes. Only one collections is allowed to be looped over in a single cache-clear. More complex cases required you to call the cache API manually from filter or listener code.

    <event-handler event="logout">
        <cache-clear aliases="showAllRequestCache" condition="event.clearCache">
            <criterion name="pid" collection="${event.pidList}"/>
            <criterion name="type" value="foobar" />
        </cache-clear>
    </event-handler>

If you have a static list, you may do this:

<event-handler event="logout">
    <cache-clear aliases="showAllRequestCache" condition="event.clearCache">
        <criterion name="pid" collection="a,b,c,d"/>
        <criterion name="type" value="foobar" />
    </cache-clear>
</event-handler>

If you have a static array, you may do this:

    <event-handler event="logout">
        <cache-clear aliases="showAllRequestCache" condition="event.clearCache">
            <criterion name="pid">
                <array>
                    <element value="a"/>
                    <element value="b"/>
                    <element value="c"/>
                    <element value="d"/>
                </array>
            </criterion>
            <criterion name="type" value="foobar" />
        </cache-clear>
    </event-handler>

Attribute	Required	Default	Description
name	required		the name of the criterion
value	optional	the value of name attribute	can also be a M2 EL expression
collection	optional		use this attribute to specify a M2 EL expression that will contain a list or array of items or you may directly write a list inside

call-method

Calls a method in the service layer and optionally put the result in a event argument. This command is available starting in Mach-II 1.8+. ColdSpring or other IoC dependency injection framework is required to use this feature.

Attribute	Values	Required	Default	Description
bean		required		specifies the name of the bean (service object) to use (corresponds to the bean id when using ColdSpring)
method		required	specifies the name of the method to call in the bean (service object)
args		optional		arguments to be passed into the method as a comma delimited list of values or a list of name value pairs
resultArg		optional		the name of the event-arg to place the result of the method call (do not use if returns void
overwrite	true,false	optional	true	whether or not to overwrite a bean of the same name if it already exists in the event object

    <!-- Using name value pairs for arguments -->
    <call-method bean="fantasyTeamService" method="getFantasyTeam"
        args="fantasyteam_id=${event.id}" resultArg="fantasyTeam" />

    <!-- Using positional arguments -->
    <call-method bean="fantasyteamService" method="getFantasyTeam"
        args="${event.id},'foobar'" resultArg="fantasyTeam" />

    <!-- A no argument method call -->
    <call-method bean="fantasyTeamService" method="getFantasyTeams"
        resultArg="fantasyTeams" />

    <!-- Setting an optional default of '0' -->
    <call-method bean="fantasyTeamService" method="getFantasyTeams"
        args="${event.id:0}" resultArg="fantasyTeams" />

Call-method can also pass in an argument collection in two ways:

    <call-method bean="playerService" method="getPlayers"
        args="${event.getArgs()}" resultArg="players" />

    <call-method bean="fantasyTeamService" method="searchFantasyTeams"
        args="argumentCollection=${event.getArgs()}" resultArg="fantasyTeams" />

Call-method supports a nested arg tags to alleviate the problem of the args attribute being a mile long with configuration:

    <!-- Using name value pairs for arguments -->
    <call-method bean="fantasyTeamService" method="getFantasyTeam" resultArg="fantasyTeam">
        <arg name="fantasyteam_id" value="${event.id}"/>
        <arg name="type" value="${event.foobar}"/>
    </call-method>

    <!-- Using positional arguments -->
    <call-method bean="fantasyteamService" method="getFantasyTeam" resultArg="fantasyTeam">
        <arg value="${event.id}"/>
        <arg value="${event.foobar}"/>
    </call-method>

If you use nested arg tags within the call-method command, you must either choose name/value pairs or positional arguments. A combination of both is not supported.

event-arg

An <event-arg> node sets an argument in the current event being handled. This event argument can then be accessed throughout the life of the event.

Order of decisions for deciding the value of the event-arg for event-arg:

Defining a variable attribue will override any value attribute or nested XML
Defining a value attribute will override any nested XML
Nested XML is used last

Attribute	Values	Required	Default	Description
name		required		specifies the variable name for the event argument
value		optional		specifies the value of the event-arg (also supports EL expressions and complext datatypes in XML starting in 1.8+)
variable		optional		Defines a variable to set as the value in the event. This must be a variable with scope. This attribute is for legacy integration only. This attribute is mutually exclusive with the value attribute.
overwrite	boolean	optional	true	If set to false, event-arg works like `<cfparam>` and will not overwrite an existing event-arg

Static value for event-arg:

    <event-handler event="myEvent" access="public">
        <event-arg name="pageTitle" value="This is my page title!" />
        <view-page name="myPage" />
    </event-handler>

Using EL expressions (1.8+):

    <event-handler event="myEvent" access="public">
        <event-arg name="id" value="${event.someBean.id}" />
        <view-page name="myPage" />
    </event-handler>

Defining complex datatypes (1.8+) - struct:

    <event-handler event="myEvent" access="public">
        <event-arg name="ids">
            <struct>
                <key name="a" value="1"/>
                <key name="b" value="2"/>
            </struct>
        </event-arg>
    </event-handler>

Defining complex datatypes (1.8+) - array:

    <event-handler event="myEvent" access="public">
        <event-arg name="ids">
            <array>
                <element value="1"/>
                <element value="2"/>
            </array>
        </event-arg>
    </event-handler>

As of Mach-II 1.9, you can nest M2EL syntax in complex datatypes like structs and arrays.

event-bean

An <event-bean> node creates a bean in the event and populate the bean with properties from the event.

Attribute	Values	Required	Default	Description
name		required		the name of the bean in the event
type		optional*		the type of the bean to create
fields		optional		the fields in the event to set in the bean
reinit	boolean	optional	true	allows you to reuse and repopulate the bean if it is available in the Event object. Will not create a new bean if a bean already exists in the Event with the name specified.
autopopulate	boolean	optional	false	if true the event-bean command will inspect the bean and automatically setup any inner-beans and fields to be populated by this command

    <event-handler event="myEvent" access="public">
        <event-bean name="person" type="path.to.User">
            <inner-bean name="address" prefix="address" />
        </event-bean>
    </event-handler>

The type attribute is only optional if you want to use a bean from an event-arg. Omitting the type attribute automatically sets the reinit attribute to false.

inner-bean

New in Mach II 1.8 is the ability to handle beans composed of other beans. This done using the inner-bean tag in the xml file. This feature works in conjunction with the form tags which allow binding to a cfc and any children cfcs.

Attribute	Required	Default	Description
name	required		the name of the inner bean
prefix	optional	the value of name attribute	this is what each field in the form should be prefixed with
fields	optional		the fields in the event to set in the bean

You can also use the field tag below to specify specific field you want to ignore or to provide a value for using Mach II's Expression Language (EL). You might want to ignore a field to prevent a user from adding some data to a bean via a form field or url var. You can do this by using the field tag below.

    <event-bean name="user" type="project.model.UserModel" autopopulate="true">
        <field name="id" ignore="true" />
        <field name="birthdate" value="${event.birthmonth}/${event.birthday}/${event.birthyear}" />
    </event-bean>

field

The second field tag in the above example shows how you can use Mach II EL to concatenate several form fields together in put that in the user bean. In addition to data from the event object you can also pull information from the the Mach II properties scope. You can also use the field tag inside of an inner-bean tag.

Attribute	Required	Default	Description
name	required		the name of the field
ignore	optional	false	ensure that this field is not populated by the event-bean command
value	optional		the value to place in the field which can be an expression or a static string value

For more information on beans, see our Introduction to Beans

event-mapping

Attribute	Required	Description
event	required	the "event name" of the mapping to be referenced
module	optional	the module in which the actual event to map to exists
mapping	required	the actual event to map to

The <event-mapping> command is used to map an event name to an actual existing event in the config file. This is how you would set up an event-mappings in your event-handler.

    <event-handler event="myEvent" access="public">
        <event-mapping event="loginSucceeded" mapping="home" />
        <event-mapping event="loginFailed" mapping="login" />
        <notify listener="loginListener" method="processLoginAttempt" />
    </event-handler>

Then, in your LoginListener you could reference the mappings you created like this:

    <cfif loginIsSuccessful>
        <cfset announceEvent("loginSucceeded", arguments.event.getArgs()) />
    <cfelse>
        <cfset announceEvent("loginFailed", arguments.event.getArgs()) />
    </cfif>

The announceEvent() methods would then actually announce the "home" or "login" events as defined in your mach-ii.xml config file. Of course, from within your listener, you could have simply announced the "home" or "login" events explicitly, but the event-mapping approach allows you to use a more meaningful naming convention, and also allows you to look at your event handler and observe the two possible outcomes of the that listener method call without even opening the listener file. The choice on whether or not to use event-mappings really comes down to developer preference.

As of Mach-II 1.9+, we support M2EL syntax in the value of event and module nodes.

    <event-handler event="myEvent" access="public">
        <event-mapping event="${properties.validLoginEvent:loginSucceeded}" mapping="home" />
        <event-mapping event="${properties.invalidLoginEvent:loginFailed}" mapping="login" />
        <notify listener="loginListener" method="processLoginAttempt" />
    </event-handler>

Remember, commands within event-handlers and subroutines are processed in the order they are defined. Place event-mapping commands before any code they may announce an event that relies on the event-mapping.

execute

An <execute> command is defined within an <event-handler> node, and executes a subroutine

Attribute	Values	Required	Description
subroutine		required	name of the subroutine to execute

    <event-handler event="myEvent" access="public">
        <execute subroutine="mySubroutine" />
    </properties>

filter

An <filter> command is defined within an <event-handler> node and runs an event-filter where defined.

Attribute	Values	Required	Description
name		required	name of the event-filter to execute

    <event-handler event="myEvent" access="public">
        <filter name="someRegisteredFilter">
    </properties>

If needed, run-time parameters can be defined right within filter command inside the event handler.

    <event-handler name="someEvent" access="public">
        <filter name="someFilter">
            <parameter name="myRunTimeParamName" value="myParamValue" />
        </filter>
        <page-view name="somePage">
    </event-handler>

The first thing to note is that when created at run-time within a <filter> command, rather than when defined as configure-time parameters within an <event-filter> node, the <parameters> node is not utilized, and each parameter declaration is a direct child to the <filter> node. The second thing to note is that run-time parameters can NOT be accessed from within the filter CFC using the methods outlined above, and instead, they are passed as an argument via <cfargument> called paramArgs that is passed to the filterEvent() method by Mach-II.

As of Mach-II 1.9+, we support M2EL syntax in the value of parameter nodes.

    <event-handler name="someEvent" access="public">
        <filter name="someFilter">
            <parameter name="userId" value="${event.user.id:0}" />
        </filter>
        <page-view name="somePage">
    </event-handler>

For more information on filters, see Introduction to Event-Filters.

Filter commands cannot next other event-handler commands in them as they will be ignored. The only child nodes filter commands can contain is are <parameter> nodes.

notify

The <notify> command is called from within an <event-handler> node and is used to call one method from one listener. Note that one event handler can call multiple <notify> commands.

Attribute	Required	Description
listener	required	specifies which listener to call
method	required	specifies which method in the listener to call
resultArg	optional	specifies the event-arg name to place in the Event for the result sent back by the listener method

    <event-handler>
        <notify listener="myListener" method="myMethod" resultArg="myResult" />
        <notify listener="myListener2" method="myMethod2" resultArg="myResult2" />
        <view-page name="myArgName" />
    </event-handler>

publish

From within an event handler <publish> publishes a message to its subscribers which typically executes a call to one or more listener objects

Attribute	Values	Required	Description
message		required	specifies which message to publish

    <event-handler event="myEvent">
        <publish message="myMessage" />
        <view-page name="myPage" />
    </event-handler>

redirect

The <redirect> command redirects the request to a new event

Attribute	Values	Required	Default	Description
event		required (or `route`)		the event the redirect will relocate to (also supports EL expression in 1.8+)
module		optional		the module the redirect will relocate to (also supports EL expression in 1.8+)
route		required (or `event`)		the URL route you want to redirect to (also supports EL expression in 1.8+). Does not support redirect persist if not using cookie as persist id storage
url		optional		the url to redirect to (also supports EL expression in 1.8+)
args		optional		a comma-delimited list of event args to attach to the redirect url (also supports EL expression in 1.8+)
persist	true,false	optional	false	a boolean that allows you to persist complex event arguments across a redirect
persistArgs		optional		a list of event args to persist across a redirect (if empty quotes or not defined - entire event is persisted) (also supports EL expression in 1.8+)
persistArgsIgnore		optional		a list of event args to not persist across a redirect (this attribute is ignored if `persistArg` is defined)
statusType	permanent,temporary,prg	optional	temporary	the HTTP status code to that is sent on the redirect (permanent = 301, temporary = 302 [default], prg [post-redirect-get] = 303)

Simple redirect:

    <event-handler>
        <redirect event="someOtherEvent" />
    </event-handler>

Simple redirect to another module:

    <event-handler>
        <redirect event="someOtherEvent" module="myModule" />
    </event-handler>

Simple redirect an URL route (redirecting to a "products" page):

    <event-handler>
        <redirect event="p" args="productId" />
    </event-handler>

Dynamic event name (1.8+):

    <event-handler>
        <redirect event="${event.nameOfEventArgWithEventNameInIt}" />
    </event-handler>

For more information on URL routes, please read about SES Improvements in Mach-II 1.8.

Warning - Config Mode

If the MACHII_CONFIG_MODE in your Application.cfc (bootstrapper) is set to 1 (always reload), redirect persist will not function correctly because it loses the reference to the persistence cache when the application is reloaded. Set your MACHII_CONFIG_MODE to 0 or -1.

Warning - Incorrect URLs

Just like the buildUrl() method and related methods, the redirect command generates URLs based on the values of properties set in your XML configuration file. If redirect URLs are incorrect, your settings are incorrect. Please read properties that affect how URLs are constructed for more information. Usually the most common developer error is that the value of urlBase is incorrect. The urlBase property must be an absolute path (no domain required). For example, if your application lives at http://www.example.com/myapp/index.cfm then change the value to "/myapp/index.cfm". This causes all generated urls ti be relative thus causing strange urls parsed by the browser such as appending a clicked link on top of another link or have an incorrect path if your application do not live at the root of your domain (the default value of the urlBase property).

Warning - Immediate Ending of Requests

Redirects in Mach-II are no different than <cflocation>. When a redirect is encountered, the browser is immediately sent headers to request a new URL. Any events that are in the Mach-II event queue will not be processed because the CFML engine aborts the request after <cflocation>.

Warning - Routes and Redirect Persist

If you are using normal redirect persists in which the persist id in append to the URL, redirect persist will not work with URL routes. You must either use redirect persist using the cookies option or not just use redirect persist in conjunction with URL routes.

view-page

Specifies a <page-view> to display and optionally place in an event-arg.

    <event-handler>
        <view-page name="pageName" contentArg="eventArgName" append="false"/>
    </event-handler>

Attribute	Values	Required	Description
name		required	name of page-view to display
contentArg		optional	name of event-arg to place the rendered output of the page into, otherwise it outputs directly
append	boolean	optional	specifies if the rendered output should be appended to the contentArg
prepend	boolean	optional	specifies if the rendered output should be prepended to the contentArg (Mach-II 1.9+ only)

Properties

array

An <array> node is defined within a <property> node, and creates an array to store as an application property.

    <properties>
        <property>
            <array>
                <element value="value1" />
                <element>
                    <value>
                        <![CDATA[I really need to use CDATA because I want to use characters that
                        invalid in normal XML such as < or > and should not be parsed]]>
                    </value>
                </element>
            </array>
        </property>
    </properties>

element

An <element> node is defined within an <array> node, and creates a new item in the array

Attribute	Values	Required	Description
value		required if not using a nested <value>	specifies value for an element in an array

    <properties>
       <property>
          <array>
             <element value="value1" />
             <element>
                <value>
                    <![CDATA[I really need to use CDATA because I want to use characters that
                    invalid in normal XML such as < or > and should not be parsed]]>
                </value>
            </element>
          </array>
       </property>
    </properties>

key

The <key> node is defined within a <struct> node, and creates a new key in the struct

Attribute	Values	Required	Description
name		required	specifies the name of the key
value		required if not using a nested `<value>`	specifies the value of the key

    <properties>
        <property>
            <struct>
                <key name="myKey1" value="value1" />
                <key name="myKey1">
                <value>
                    <![CDATA[I really need to use CDATA because I want to use characters that
                    invalid in normal XML such as < or > and should not be parsed]]>
                </value>
            </key>
            </struct>
        </property>
    </properties>

property

A <property> node defines an property (variable) to be used throughout the application. This can be a name/value pair, struct or array, or CFC

Attribute	Values	Required	Description
name		required	specifies a name for the property to be used throughout the application
value		optional	specifies a value for a simple name/value pair property
type		optional	specifies the dot delimited path to a property CFC
overrideAction	`useParent`, `addFromParent`	optional	Used to override a module property with a parent property. A value of `useParent` removes the property from the module and effectively any references to the property name in the module will reference the parent property via inheritance. A value of `addFromParent` allows you to copy a property into the module context and optionally use the `mapping` attribute. Only valid if used in a Mach-II module XML configuration file and has not effect if used in the base application.
mapping		optional	Used in conjunction with `addFromParent` value of `overrideAction` attribute to map a property in the parent to the property in the module. Only valid when used with `overrideAction="addFromParent"` in a Mach-II module XML configuration file.

    <properties>
        <property name="appName" value="myAppName" />
        <property name="myPropCFC" type="path.to.myPropertyCFC" />
    </properties>

Property Type Shortcuts

As of Mach-II 1.9, you can use a shortcut for the property type when referencing Mach-II property files that are shipped with the core framework.

Shortcut Name	Value Substituted at Runtime
`ColdspringProperty`	`MachII.properties.ColdspringProperty`
`EnvironmentProperty`	`MachII.properties.EnvironmentProperty`
`HtmlHelperLoaderProperty`	`MachII.properties.HtmlHelperLoaderProperty`
`HtmlHelperProperty`	`MachII.properties.HtmlHelperProperty`
`UrlRoutesProperty`	`MachII.properties.UrlRoutesProperty`
`CachingProperty`	`MachII.caching.CachingProperty`
`LoggingProperty`	`MachII.logging.LoggingProperty`
`GlobalizationLoaderProperty`	`MachII.globalization.GlobalizationLoaderProperty`

properties

The <properties> node is the parent node to all <property> nodes within the configuration file.

struct

A <struct> element builds a struct of key value pairs via xml. Note this struct does support nested structs and arrays.

    <struct>
        <key name="key1" value="value1" />
        <key name="key2" value="value2" />
        <key name="key3" value="value3" />
        <key name="key4" value="value4" />
        <key name="key5">
            <array>
                <element value="value1" />
                <element value="value2" />
            </array>
        </key>
    </struct>

value

The <value> node specifies the value of an array element or struct key

    <array>
        <element>
                <value>myValue1</value>
        </element>
        <element>
            <value>myValue2</value>
        </element>
    </array>

    <struct>
        <key name="key1"><value>Value1</value></key>
        <key name="key2"><value>Value2</value></key>
    </struct>

Plugins & Filters

plugin

The <plugin> command registers a plugin CFC to be processed by Mach-II at each of nine request plugin points

Attribute	Values	Required	Description
name		required	specifies the name of the plugin to be referenced throughout the configuration file
type		required	specifies the dot delimited path to the plugin CFC
overrideAction	addFromParent	optional	Used to add or override a plugin defined in a module using module override XML. Plugins are not inherited in the traditional way so the value of `addFromParent` is not supported in plugins (unlike listeners, filters and properties).
mapping		optional	Used exclusively with overrideAction and indicates the name of the parent plugin to use.

    <plugins>
        <plugin name="myPlugin" type="path.to.myPlugin" />
    </plugins>

plugins

The <plugins> node is the parent node to all <plugins> nodes within the configuration file.

Attribute	Values	Required	Description
runParent	`after`, `before`, `none` (defaults to `after`)	false	Defines if or when parent (base application) plugins should be run. This attribute only applies to Mach-II module XML configuration files and has no effect if defined in a base application. A value of `after` will run the defined module plugins first then the parent plugins, a value of `before` will run the parent plugins first then the module plugins and a value of `none` will run only the module plugins with no parent plugins whatsoever. The default value is `after` if not defined and the XML configuration file is a module.

event-filter

An <event-filter> node registers an event-filter CFC for use throughout the configuration file.

Attribute	Values	Required	Description
name		required	specifies the handle to reference the event filter by in the configuration file
type		required	specifies the path to the CFC for the event filter
overrideAction	useParent,addFromParent	optional	Specifies what type of override action to take when overriding this element

Without configure parameters:

    <event-filters>
        <event-filter name="myFilter" type="dot.delimited.path.to.myFilter" />
    </event-filters>

With configure parameters:

    <event-filters>
        <event-filter name="myFilter" type="dot.delimited.path.to.myFilter">
            <parameters>
                <parameter name="key1" value="valueA"/>
                <parameter name="someStruct">
                    <struct>
                        <key name="someKey" value="z"/>
                        <key name="anotherKey" value="x"/>
                    </struct>
                </parameter>
            </parameters>
        </event-filter>
    </event-filters>

<element-filters> is the parent node node for all `<element-filter>` nodes.

Listeners

listener

A <listener> node registers a listener for use throughout the mach-ii.xml configuration file.

Attribute	Values	Required	Description
name		required	specifies which handle for the listener throughout the configuration file
type		required	specifies the dot delimited path to the listener CFC
overrideAction	`useParent`, `addFromParent`	optional	Used in override XML for Mach-II modules to override module listeners with listeners that exist in the parent (base application). Only valid when used in Mach-II module XML configuration files. A value of `useParent` will remove the listener from module context which effectively will cause any references to that listener in the module to use the parent listener. While similar, a value of `addFromParent` copies a listener from the parent into the module context. This value can be used in conjunction with the `mapping` attribute.
mapping		optional	Used with the `addFromParent` value of the `overrideAction` attribute and allows you to mapping a parent listener name to the module listener.

Without configure time parameters:

    <listeners>
        <listener name="myListener" type="path.to.myListener" />
    </listeners>

With configure time parameters:

    <listeners>
        <listener name="myListener" type="path.to.myListener">
            <parameters>
                <parameter name="key1" value="valueA"/>
                <parameter name="someStruct">
                <array>
                    <element value="z"/>
                    <element><value>x</value></element>
                </array>
                </parameter>
            </parameters>
        </listener>
    </listeners>

listeners

The <listeners> node is the parent to all `<listener>` nodes within the configuration file.

Event-Handlers

event-handler

An <event-handler> node defines the commands necessary to handle any event in the application.

Attribute	Values	Required	Default	Description
event		required		specifies the event to handle
access	`public`, `private`	optional	public	specifies whether the event should be able to be called from the URL
mapping		optional		Used in conjunction with the `overrideAction` attribute with the value of `addFormParent` to map a differently named parent event-handler to this event-handler declaration. Only applies to Mach-II module XML configuration files.
overrideAction	`useParent`, `addFromParent`	optional		Used in override XML in Mach-II modules override a module event-handler with an event-handler that exists in the parent. A value of `useParent` removes the event-handler from module context. While modules do inherit parent event-handlers, you cannot directly invoked an in inherited event-handler in the context of a module via the URL. Effectively, `useParent` does not allow you to announce an event handler in the context of the module and forces you to use the URL to the parent event-handler. A value of `addFromParent` "copies" the parent event-handler into the module context. This value can be used in conjunction with the `mapping` attribute. See here for examples.
secure	true, false	optional	null	Defines whether this event-handler contained should be secure or non-secures (http/https)

    <event-handler event="myEvent" access="public">
        <notify listener="myListener" method="myMethod" resultArg="myResult" />
        <event-arg name="myArgName" value="myArgValue" />
        <execute subroutine="mainLayout" />
    </event-handler>

event-handlers

<event-handlers> is the parent node node for all `<event-handler>` nodes.

Attribute	Values	Required	Default	Description
secureDefault	true, false	optional	null	Defines whether the event-handlers contained within this node should be secure or non-secures (http/https). This is a global setting unless set individually by the event-handler node.

Includes & Modules

include

The <include> command is called from within an <includes> node, and includes another Mach-II configuration file into another mach-ii.xml configuration file. Use ./ to indicate a relative path. Also supports ../ to move up a directory.

Attribute	Values	Required	Default	Description
file	string path	required		path to .xml file to include
override	boolean	optional	false	Sets directive on whether to override elements with a namespace conflict or to throw an exception

    <includes>
        <include file="./myOtherFile.xml" override="false" />
    </includes>

Must use absolute paths, CFML mapped path or relative paths. Relative paths are relative from the mach-ii.xml configuration file that makes the include in which the path must start with ./ to indicate it is a relative. You can also use ../ within a path to indicate that you want to move up a directory.

Warning: Include File Must Be a DTD Compliant File

All include files must have a root node of <mach-ii> just like all other Mach-II XML configuration files. Other child nodes are optional (meaning you can includes with just properties or a mix of nodes like listeners / plugins -- it is not required that all nodes are present).

Incorrect Syntax:

    <properties>
        <property name="foo" value="1"/>
        <property name="bar" value="2"/>
    </properties>

Correct Syntax:

    <mach-ii>
        <properties>
        <property name="foo" value="1"/>
        <property name="bar" value="2"/>
        </properties>
    </mach-ii>

includes

<includes> is the parent node node for all `<include>` nodes.

module

An <module> node defines one or more pier or sub-applications to be used within the current application.

Attribute	Values	Required	Description
name		required	specifies which handle to use for the module throughout the configuration file
file		required	specifies the path to the configuration file for the module

    <modules>
        <module name="myModule" file="path.to.myModuleConfig.xml" />
    </modules>

modules

The <modules> element is the parent node to all the <module> nodes within the application.

Message-Subscribers

message (in message-subscriber)

The <message> node defines one or more listeners which will respond to a given publish command in any event handler.

Attribute	Values	Required	Description
name		required	specifies which handle for the message throughout the configuration file
multithreaded	true,false	required	specifies whether or not the message will be multi-threaded
waitForThreads	true,false	required	specifies whether or not the message will wait for other threads to complete before processing. If nothing is specified, then wait until the request timeout is reached.
timeout	numeric	optional	The time to wait to join threads in seconds before throwing an error (only applies in multi-thread environments when `waitForThreads` is true)
overrideAction	useParent,addFromParent	optional
mapping		optional

    <message-subscribers>
        <message name="someMessage" multithreaded="true" waitForThreads="true">
            <subscribe listener="myListener1" method="someMethod1" resultArg="myVar1" />
            <subscribe listener="myListener2" method="someMethod2" resultArg="myVar2" />
            <subscribe listener="myListener3" method="someMethod3" resultArg="myVar3" />
        </message>
    </message-subscribers>

message-subscribers

The <message-subscribers> element is the parent node to all the <message> nodes within the application.

subscribe

A <subscribe> node defines a listener or bean and method as a subscriber to a particular message. Support for beans (using call-method) is available in Mach-II 1.8+. Using the bean attribute is exactly like using the call-method command in event-handlers.

Using the bean attribute requires the use of ColdSpring or other IoC framework. Beans can be manually wired into subscribers using a custom property and the callback architecture provided by the framework.

Attribute	Required	Description
listener	optional	the listener to call
bean	optional	the bean to use
method	required	the method to call in the specified listener
args	optional	a list of args to use when using the `bean` attribute or can optionally use nested `arg` nodes (cannot be used with the `listener` attribute and is mutally exclusive with the `bean` attribute
resultArg	optional	the variable name of the return data from the method call in the listener / bean

<message-subscribers>
    <message name="needInformation">
        <subscribe listener="myListener1" method="myMethod1" resultArg="myVar1" />
        <subscribe listener="myListener2" method="myMethod2" resultArg="myVar2" />
        <subscribe bean="userService" method="getUser" args="userId=${event.userId}" resultArg="myVar3" />
        <subscribe bean="orderService" method="getOrdersByUser" resultArg="myVar3">
                <arg name="userId" value="${event.userId}"/>
        </subscribe>
    </message>
</message-subscribers>

Nested <arg> nodes are only supported in Mach-II Simplicity (1.8) and higher.

Views

page-view

A <page-view> node registers a .cfm template for use throughout the configuration file.

Attribute	Values	Required	Description
name		required	specifies which handle for the page-view throughout the configuration file
page		required	specifies a relative path to the actual .cfm template to be rendered

    <page-views>
        <page-view name="myPageName" page="views/myPage.cfm" />
    </page-views>

page-views

The <page-views> node is the parent node to all `<page-view>` nodes within the configuration file.

view-loader

A <view-loader> node registers a component that loads page-views by convention to be used throughout the configuration file. Configuration is provided to the view-loader through standard parameters (just like filters, listeners, plugins and properties) and configuration details depend on the loader defined. See documentation for your chosen view-loader for configuration parameter documentation.

Attribute	Values	Required	Description
type		required	specifies the dot path location of the view-loader

Simple registration example using the PatternViewLoader:

    <view-loader type="MachII.framework.viewLoaders.PatternViewLoader" />

Complex registration example using the PatternViewLoader:

    <view-loader type="MachII.framework.viewLoaders.PatternViewLoader">
        <parameters>
            <parameter name="pattern" value="/views/**/*.cfm"/>
            <parameter name="exclude">
                <array>
                    <element value="/views/productsServices/**"/>
                    <element value="/views/bizTools/**"/>
                    <element value="/views/register/**"/>
                </array>
            </parameter>
        </parameters>
    </view-loader>

Subroutines

subroutine

<subroutines> were introduced in Mach-II 1.5 and define a series of Mach-II configuration commands to be executed inline

Attribute	Values	Required	Description
name		required	specifies which handle to use for the subroutine throughout the application

    <subroutines>
        <subroutine name="mySubroutine">
            <publish message="myMessage" />
            <view-page name="myPage1" />
            <view-page name="myPage2" />
            <view-page name="myPage3" />
        </subroutine>
    </subroutines>

subroutines

The <subroutines> node is the parent node to all <subroutine> nodes within the configuration file.

General

mach-ii

The <mach-ii> command is root element for all Mach-II configuration files.

Attribute	Values	Required	Description
version		required	specifies the version of the DTD being used for configuration

    <mach-ii version="1.6">
        <!-- application configuration -->
    </mach-ii>

parameter

The <parameter> node sends custom parameters to controller layer objects (Filters, Plugins, Listeners, Properties) for use within the CFC.

Attribute	Values	Required	Description
name		required	the name of the parameter
value		required	the value of the parameter

    <parameters>
        <parameter name="myParamName" value="myValue" />
    </parameters>

Parameters can also nest struct and array datatypes.

parameters

The <parameters> node is the parent node to all `<parameter>` nodes within the configuration file.