-
Notifications
You must be signed in to change notification settings - Fork 24
Introduction to Event Filters
- Typical Uses for an Event-Filter
- MachII Configuration File Fragment
- Basic Event-Filter CFC
- Anatomy of a Filter
- Using Parameters with Filters
This article looks at event-filters and how they should be used. Filters enable per-event flow control in Mach-II applications, and are easily added to Mach-II events through a single line in the XML configuration file. A simple example would be the addition of security or logging to a specific Mach-II event, or conditionally redirecting to a different event based on some value. By developing a filter and adding this filter to the event, this additional functionality can be added to or removed from the event without touching the business logic involved.
- Checks to see if an user is logged and redirects the user to a login page if they are not logged in.
- Checks to see if a user has the required privileges / roles / permissions / credentials to perform an action or view information.
- Execute a subroutine dynamically at runtime
- Announce an event dynamically at runtime
- To change the request timeout for an event (useful if the event is for scheduled processes that may take awhile)
- Any logic that may or may not change the flow of your application
Feel free to add other typical examples.
<mach-ii>
<event-filters>
<event-filter name="someFilter" type="filters.someFilter"/>
</event-filters>
<event-handlers>
<event-handler name="someEvent" access="public">
<filter name="someFilter"/>
<page-view name="somePage"/>
</event-handler>
</event-handlers>
</mach-ii> <cfcomponent extends="MachII.framework.EventFilter" output="false">
<cffunction name="configure" access="public" output="false" returntype="void"
hint="Configures the filter">
<!--- Does nothing --->
</cffunction>
<cffunction name="filterEvent" access="public" output="false" returntype="boolean"
hint="Runs the filter event">
<cfargument name="event" type="MachII.framework.Event" required="true" />
<cfargument name="eventContext" type="MachII.framework.EventContext" required="true" />
<cfreturn true|false />
</cffunction>
</cfcomponent>A filter is nothing more than a regular CFC. There are however a few considerations to keep in mind when writing your filters for Mach-II. First off, all filters must extend MachII.framework.EventFilter, as seen in the <cfcomponent> tag above. Secondly, filters must always contain at least two methods - configure() and filterEvent().
The configure() method is required and called by Mach-II when the framework loads. Here you can perform any kind of configuration logic needed, but generally it is left blank. It is worth noting that the filter should not implement an init() method, as the init() method is used in the filter's superclass MachII.framework.EventFilter and should not be overridden. If you would like more information about why we use the configure() method, please read our FAQ on what are the differences between configure() and init() methods?.
The filterEvent() method is called by Mach-II when it encounters a <filter> command inside an event-handler and is where you perform your filter's business logic. This method takes three arguments, Event, EventContext and an optional paramArgs objects. Using the first two objects you can access eventArgs, announce other events and execute subroutines. For more information on this functionality take a look at the Event and EventContext objects to see what public methods are available.
Filters typically return a boolean in order to affect processing of the event. Returning true will cause the current event to continue processing, while returning false will cause the current event to stop processing immediately and the next event in the queue will start processing. When returning false, be sure to announce a new event to reflect the change in the application flow, otherwise nothing will happen.
Note: Your filter must have a method named filterEvent. Developer defined methods not named filterEvent will not be called by the framework. Also, please note that if your filter will be utilized to change the content to be displayed (i.e. using eventContext.displayView()), you must change the "filterEvent" attribute output="true" in order for the content to be displayed. This is part of the new heavy duty whitespace suppression functionality we put into Mach-II 1.8.
Parameters are an easy way to send additional arguments to the filter for processing. In Mach-II, there are two kinds of parameters: configure-time parameters and run-time parameters.
If needed, configure-time parameters are defined in the main filter declaration:
<event-filter name="someFilter" type="filters.someFilter">
<parameters>
<parameter name="myParamName" value="myParamValue" />
</parameters>
</event-filter>Configure-time parameters can then be accessed within the filter using a variety of methods made available to the filter by its superclasses.
| Method Name | Syntax | Description |
|---|---|---|
| getParameter | getParameter('nameOfParameter', 'defaultValue') | Gets a configuration parameter value, or a default value if not defined. The defaultValue is optional. |
| getParameters | getParameters() | Gets the full set of configuration parameters for the component. |
| isParameterDefined | isParameterDefined('nameOfParameter') | Checks to see whether or not a configuration parameter is defined. |
Using getParameters() to grab configure-time parameters for use in the method:
<cffunction name="filterEvent" access="public" returntype="boolean">
<cfargument name="event" type="MachII.framework.Event" required="yes" />
<cfargument name="eventContext" type="MachII.framework.EventContext" required="yes" />
<!--- grab configure-time parameters --->
<cfset var myConfigureTimeParams = getParameters() />
<cfreturn true|false />
</cffunction>For a full list of the methods available to the filters, remember your filter will extend from MachII.framework.EventFilter, so by nature, it also inherits the methods from the BaseComponent.
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.
<cffunction name="filterEvent" access="public" returntype="boolean">
<cfargument name="event" type="MachII.framework.Event" required="true" />
<cfargument name="eventContext" type="MachII.framework.EventContext" required="true" />
<cfargument name="paramArgs" type="struct" required="false" default="#StructNew()#" />
<!--- notice the third argument above, paramArgs is automatically passed in by Mach-II --->
<cfreturn true|false />
</cffunction>Now we can see that we have access to both configure-time parameters and run-time parameters within the filter CFC.
As of Mach-II 1.9+, runtime parameters values can contain M2EL syntax. This is useful for dynamic value of parameters are runtime. For more information on M2EL syntax, see the quick reference guide reference above.
<event-handler name="someEvent" access="public">
<filter name="someFilter">
<parameter name="userId" value="${event.user.id:0}" />
</filter>
<page-view name="somePage">
</event-handler>