Helpers

Model-Glue provides a great separation of concerns when it comes to your web application. It helps you clearly differentiate between views, controllers, and model files. However, sometimes there are utilities that don't quite fit in the MVC design. Consider a utility that formats strings such that URLs and email addresses are automatically linked. Where would you put that? It isn't a controller concern. It isn't a model. You could simply put it in a view file, but then you end up (possibly) repeating the same function in multiple places.

Model-Glue 3 solves this problem by creating support for what it calls "helpers". Helpers are libraries of user defined functions or CFCs of methods. By placing these files in the proper location. Model-Glue 3 will automatically load them and make them accessible via the new helpers scope. This scope is available to both controller and views file. Let's take a look at a simple example.

First, you have to know where Model-Glue will look for helper files. Open ColdSpring.xml and look for the helperMappings setting. Most likely it will look something like this:

<property name="helperMappings"><value>/myapplication/helpers</value></property>

If you used the default Model-Glue skeleton application, you should see a helpers folder. Create a new file called udf.cfm and place this UDF in it:

<cfscript>
function formatDateTime(dt) {
    return dateFormat(dt) & " " & timeFormat(dt);    
}
</cfscript>

Open up one of the views from your site and add this line:

<cfoutput>#helpers.udf.formatDateTime(now())#</cfoutput>

Run the site and you should see something like this:

30-Apr-09 09:32 PM

Ok, so what happened here? First off, pay attention to how I called the script: helpers.udf.formatDateTime. "helpers" comes from Model-Glue 3 itself. This is the root scope created by Model-Glue 3 to hold all your utilities. "udf" comes from the file name. If I had called the file udfs.cfm, I'd have to use helpers.udfs.formatDateTime. Finally, "formatDateTime" is simply the UDF itself. This exact same call can be made in any controller as well.

As another example, create a new file in the helpers folder called utils.cfc. Drop the GoldenBirthay UDF in it:

<cfcomponent output="false">

<!---
Returns a 'golden birthday', or the date when your birthday day of month equals your age.

@param birthday      The date of birth. (Required)
@return Returns a date.
@author Joshua Siok (jsiok@smp.org)
@version 0, April 30, 2009
--->
<cffunction name="goldenBirthday" access="public" returntype="date">
    <cfargument name="birthDate" type="date" required="yes">
    <cfreturn dateAdd("yyyy", day(birthDate),birthDate)>
</cffunction>

</cfcomponent>

Based on the rules discussed before, we know that we can call this method by using the helpers scope, the file name, and the method name:

<cfoutput>#helpers.utils.goldenBirthday(createDate(1973,4,8))#</cfoutput>

One last note. The files in the helpers folder (or folders if you have defined more than one) are cached. If your Model-Glue application is not set to reload on every request, you will have to force a reload with the proper URL variable.