Using Mach II Expression Language Syntax

Table of Contents

1. Overview
2. EL Expression Syntax
3. Known Limitations
4. Further Examples

Overview

The Mach-II Expression Language is based off OGNL for Java and is currently more basic than the full OGNL expressions. It is a simplified expression language which is shorthand for accessing data. The general use case for this syntax is for referencing certain variables or information in the XML of the Mach-II controller. The standard ## syntax used in CFML is not supported in the Mach-II XML.

OGNL stands for Object-Graph Navigation Language; it is an expression language for getting and setting properties of Java objects, plus other extras such as list projection and selection and lambda expressions. You use the same expression for both getting and setting the value of a property. (source: http://en.wikipedia.org/wiki/OGNL)

Many other frameworks such as Spring, Struts2 and Apache Click use this type of EL syntax. They use a syntax resembling #{} but Mach-II opts for a syntax resembling ${} because that is what ColdSpring supports, and that is what Mach-II originally supported with bindable property placeholders. It is also less confusion if a # is not used.

M2EL is not meant as a short-hand replacement to access any CFML variable and should not be thought of as Mach-II's version of the CFML ## syntax. In general, CFML variable and expression support in the XML is thought of as not good practice and should be avoided. It is a simplified expression language which is shorthand for accessing data.

EL Expression Syntax

As of Mach-II version 1.9, the general M2EL syntax can be defined as:

    ${[event|properties].[variable_name|method_name][:default_value]}

This means there are two and only two "scopes" in the M2EL:

    ${event.*}
    ${properties.*}

The asterisk above can be replaced with variable names or method names as appropriate. For example, to access the Event variable named "key_id", the following syntax would be used:

    ${event.key_id}

Note that you do not have to use the "getArg" method to reference the "key_id" above, but this syntax is supported as well. The following example is equivalent to the previous example:

    ${event.getArg("key_id")}

A default value of the desired variable or method can be specified with the : syntax above. For example, if "key_id" doesn't exist in the Event, then use the default of "0":

    ${event.id:0}

Of if you wanted a zero length string for a "firstName" Event variable:

    ${event.firstName:''}

Nesting methods using dot notation is also possible with this syntax. The EL syntax also assumes all variables named "XYZ" are actually methods on the object named "getXYZ" (except in the initial case, then it knows to use getArg() instead). The following examples are all equivalent to each other:

    ${event.getArg("person").getFirstName().getAddress().getAddress1():
    ${event.person.getFirstName().getAddress().getAddress1():
    ${event.person.firstname.getAddress().address1}
    ${event.person.firstname.address.address1}

If a real method is needed that doesn't fall under the "getXYZ" format, use the full method name ending with (). The following example calls the "displayAddressString" method on the Address object.

    ${event.person.firstname.address.displayAddressString()}

M2EL also supports getting the entire event args structure:

    ${event.getArgs()}

Since the "getArgs" method returns a structure, M2EL can reference the structure keys as if they were properties on that structure. The same is true for any user-defined structure. Referencing arrays, however, is not supported. The following examples demonstrate this:

    ${event.getArgs().key_id}
    ${event.myStruct.someKey})

M2EL also support simple expressions. These expressions evaluate to standard ColdFusion boolean results ("YES" or "NO"):

    ${event.foo eq properties.foo}
    ${event.foo eq 'bar'}
    ${event.bar neq 1}

Some string concatenation is also possible using the "/" operator. For example:

    ${event.birthMonth}/${event.birthday}/${event.birthyear}

Known Limitations

• Although referencing a structure's keys is supported using dot notation, referencing an array's members is not currently supported.
• You cannot pass in arguments to method calls. I.E. ${event.person.firstname.address.displayAddressString('home')} is not supported.
• General CFML functions (such as Trim or DateFormat) cannot be referenced in the M2EL, only methods accessible by the Event object.
• This is not meant as a short-hand replacement to access any CFML variable and should not be thought of as Mach-II's version of the ColdFusion ## syntax. In general, CFML variable and expression support in the XML is thought of as not good practice and should be avoided.

Further Examples

• The copyToScope() method available in all views uses the M2EL syntax