What is the Event Object and What Does it Do?

Mach-II is event-driven. The event object is at the heart of the Mach-II request lifecycle. Mach-II automatically puts all the form and URL variables from the current request into the event object, and your application can also programmatically put data into and pull data from the event object. The ability to access everything from a single event object is an extremely convenient way to deal with the event's data.

The event object encapsulates your Form and URL scope data into a single and unified data access object. When a request begins in a Mach-II application, the framework "copies" all the Form and URL scope data into a object called the Event objection. This makes the Event object like a unified scope. The behavior is similar to how Fusebox uses the attributes scope.

If a variable name conflict occurs when the Event object is getting populated, Mach-II allows you to set scope precedence in the configure file. This configuration setting lets you decide if the Form or URL scope takes precedence. You can think of the Event object as a glorified encapsulated structure with methods that access the data contained inside. Instead of directly referencing Form or URL scope parameters in your application, you access the Event object.

    <cfset variables.myArg = event.getArg("someArg") />

The Event object can be passed around to your listeners, plugins and filters. It is best practice to pass any data needed in your model from the Event object in your listeners instead of passing in the Event object into your model. This eliminates a dependency on the Mach-II framework in your model.

Event Object Methods

The Event object is the heart of the Mach-II request lifecycle and is used throughout the framework. It is available in all event-filters, listeners, plugins, properties objects and views. In all areas except for views, the Event object is passed in as an argument (arguments.event) and in views you should access the Event object by referencing event.nameOfMethod() (which is an unqualified reference since no scope is indicated). See the FAQ named How should I access the Event object in my views? for more information on the reasons why you should not indicate a scope name.

Common Event Object Methods

Name of Method	Syntax	Description
getArg	getArg("nameOfArg", "optionalDefault")	Gets an argument from the Event object. If an argument if the passed named is not defined, Mach-II will return "" (zero length string) or the optional default if defined.
setArg	setArg("nameOfArg", "value")	Sets an argument to the Event object. Overwrites an argument if a namespace conflict occurs.
isArgDefined	isArgDefined("nameOfArg")	Returns a boolean on whether or not an argument exists in the Event object under the passed argument name.
getArgs	getArgs()	Returns a struct of the current args in the Event object.