How do you organize your small reusable cffunctions?

This is a reprint of a blog post I did back on June 13, 2007. I've been using this method for quite sometime and it works great! YMMV.

Who doesn't like user-defined functions (UDFs)? If you have done any programming, chances are that you have used them extensively. The biggest problem that people have with them is how to include and organize them in your application.

What I've found that most people do is create a Utils.cfc or UDFs.cfc and cut and paste their UDFs that they want to use into the component as demonstrated below:

<!--- UDFs.cfc --->
<cfcomponent output="false">

<cffunction name="init" access="public” returntype="Any" output="false">
  <cfreturn this>
</cffunction>

<cffunction name="myUDF1" access="public" returntype="Any" output="false">
</cffunction>

<cffunction name="myUDF2" access="public" returntype="Any" output="false">
</cffunction>

</cfcomponent>

Once you have all the UDFs that your application will be using pasted into your component, you will need to make the UDFs available to your application. Almost everyone I've seen does this loading by the component into the application scope. The following line is placed into the onApplicationStart() if you're using Application.cfc or by just adding it into the Application.cfm if you're using that:

<cfset application.functions = CreateObject("component", "udfs").init()>

Whichever one you're using, Application.cfc or Application.cfm, the results are the same; all your UDFs are available to your application and you can use them freely throughout. The only difference is what variable name you use. I use application.functions, some use application.utils or application.udfs; doesn’t matter, again, the results are the same.

There is one problem that I have with this approach though, it's cumbersome and the UDFs component will get huge. The problem with having such a huge component file is editing it becomes a nightmare since scrolling through thousand of lines of code isn't very fun and also I've noticed that CFEclipse bogs down on huge files. Sure code collapse does provide some relief but there has to be a better way.

What I wanted was to just have one file for each UDF I was using and a way for my application to load them automatically. The reason behind this was so that if I needed to edit myUDF1, I could just open the file myUDF1.cfm and edit what I needed. I also wanted to be able to grab UDFs from CFLib.org and just drop them into my application without having to edit anything. If I ever needed to remove a UDF from my application, it would be as easy as deleting the UDF file and reinitializing my application.

To accomplish what I wanted, I modified my UDFs.cfc to 11 lines of code:

<!--- UDFs.cfc --->
<cfcomponent output="false">

  <cfset variables.udfdir = GetDirectoryFromPath(GetCurrentTemplatePath()) & "udfs">
  <cfset variables.q = "">

  <cffunction name="init" access="public" returntype="Any" output="false">
    <cfreturn this>
  </cffunction>

  <cfdirectory action="list" directory="#variables.udfdir#" filter="*.cfm" name="variables.q">

  <cfoutput query="variables.q">
    <cfinclude template="udfs\#name#">
  </cfoutput>

</cfcomponent>

So what exactly is going on?

In a nutshell, here's what’s happening: I have a directory called udfs in the same directory that I have my UDFs.cfc. This is the directory that I put all of my UDF CFM files. What the UDFs.cfc does is scan this directory when it is called and automatically includes each CFM file it finds. Thus it automatically loads any UDFs in the UDFs folder into itself (commonly called a "mixin").

So my goal is reached! I have each UDF in its own file so I don't have to scroll through a huge component file to find it. I can now open and edit it easily. By just looking at the directory, I know what UDFs my application is using. I can automatically add a UDF from CFLib.org by just saving the text from browser into a file in the directory. Plus if I no longer need to use the UDF in my application, I simply delete the file from the directory and it's removed from my application during the next re-init. All this is done without having to touch the main UDFs.cfc file.

Below is an example of what one of the UDF CFM files looks like. The file is called fullLeft.cfm and resides in the UDFs directory.

<!--- fullLeft --->
<cffunction name="fullLeft" access="public" displayname="fullLeft" returntype="string" output="false">
  <cfargument name="str" type="string" required="true">
  <cfargument name="count" type="numeric" required="true">
  <cfif not refind("[[:space:]]", arguments.str) or (arguments.count gte len(arguments.str))>
    <cfreturn Left(arguments.str, arguments.count)>
  <cfelseif reFind("[[:space:]]",mid(arguments.str,arguments.count+1,1))>
    <cfreturn left(arguments.str,arguments.count)>
  <cfelse>
    <cfif count-refind("[[:space:]]", reverse(mid(arguments.str,1,arguments.count)))>
      <cfreturn Left(arguments.str, (arguments.count-refind("[[:space:]]", reverse(mid(str,1,arguments.count)))))>
    <cfelse>
      <cfreturn left(arguments.str,1)>
    </cfif>
  </cfif>
</cffunction>

I think this depends on your programming style, go with whichever style you are most comfortable with. I find the easiest way is in application.cfm, set a variable in the application scope to a cfcomponent with all my utility functions:

<cfif not isDefined("application.utilities")>
    <cfset application.utilities = createObject("component", "Utilities")>
</cfif>

Now you can call methods in application.utitlies from anywhere. Note that if you make changes to your cfcomponent, you have to refresh your application variable with a new instance of Utilities.

if you are using Application.cfc (if you are not i would strongly suggest migrating to it from Application.cfm - its very easy to do) you can build a baseComponent.cfc with all your UDF methods and have the Application.cfc inherit from baseComponent. then in the onRequestStart method set a variable called request.app=this;

for the entiure request, you can then use request.app.methodname() to access the UDF. its very nice and simple way of handling UDFs

also, if you like you can have all your cfcs inherit from the same baseComponent so that all your cfcs have those util functions as native methods. makes unit testing cfcs very easy because the cfcs dont need to reply on a passed (injected) reference to the UDf component, they are decedents of it!

one challenge with this approach is that the extends attribute of a cfc cannot be an expression... so depending on how you package your components, this can be hard to implement. the easiest way to handle it is with a coldfusion mapping.

hth Jon

We use .cfm files for function libraries and call the appropriate file with cfinclude. Some of the .cfm files have been downloaded from cflib.org and others are written by us. The files are in a directory named UDF which is a subdirectory of another directory which is mapped to the forward slash character. The cfinclude statement is simply:

<cfinclude template="/UDF/filename.cfm">

This approach makes the functions available to all applications on the server.

We also prefer the several small library approach. Each library is topic specific (math, string, list-array etc)