DataMgr 2.5 Documentation: Named Filters

Named Filters

While the "data" argument of getRecord, getRecords, and deleteRecord (as well as the data_where argument of updateRecords) tests for equality only, filters can test for any number of operators. If, however, you find yourself using the same filters frequently with only a different value then the use of filters may seem tedious.

For example, you may want to filter events for all events on or after a certain day (by the "EventDate" field). Using filters, this could be done as this:

<cffunction name="getEvents" access="public" returntype="query" output="no">
	<cfargument name="StartDate" type="date" required="no">
	
	<cfset var aFilters = []>
	<cfset var sFilter = 0>
	
	<cfif StructKeyExists(arguments,"StartDate")>
		<cfset sFilter = {field="EventDate",operator=">=",value=arguments.StartDate}>
		<cfset ArrayAppend(aFilters)>
	</cfif>
	
	<cfreturn variables.DataMgr.getRecords(tablename="events",data=arguments,filters=aFilters)>
</cffunction>

While this is relatively easy, it is somewhat verbose. Moreover, it isn't easy to reuse.

You could, however, define a named filter on your table to make this task even easier. A named filter allows you to use a filter just by including a key of that name in the data (or data_where) argument of a method.

By xml:

<table name="events">
	<filter name="StartDate" field="EventDate" operator="GTE" />
</table>

or by using setNamedFilter

<cfset DataMgr.setNamedFilter("events","StartDate","EventDate",">=")>

Once that is done, the previous example could be accomplished using the following code:

<cffunction name="getEvents" access="public" returntype="query" output="no">
	<cfargument name="StartDate" type="date" required="no">
	
	<cfreturn variables.DataMgr.getRecords(tablename="events",data=arguments)>
</cffunction>