Custom functions can be a powerful tool for encapsulating common business rules in one central location. Any business rules implemented in cfscript that could be reused in your application may be a good candidate for moving to custom functions. This article addresses creating custom functions and reusing them within your ColdFusion applications.
Creating and Using a ColdFusion Custom Function
ColdFusion Script is a new feature added to ColdFusion 5.0. One powerful feature of ColdFusion Script is the ability to create and use custom functions. Custom Functions can be defined in a manner similar to JavaScript; all you have to do is create a cfscript block inside a coldfusion page, and declare a function.
<cfscript>
function MyDollarFormat(money_string){
money_string = DollarFormat(money_string);
money_string = RemoveChars(money_string, Len(money_string)-3, 3 );
return(money_string);
}
</cfscript>
<cfset value = "1000">
<cfset dfvalue = DollarFormat(value)>
<cfset mdfvalue = MyDollarFormat(value)>
<cfoutput>
The unformatted value is: #value#<br>
The DollarFormat value is: #dfvalue#<br>
The MyDollarFormat value is: #mdfvalue#
</cfoutput>
If you already know JavaScript, the code above should look familiar. First we declare the function using the "function" keyword. The next keyword "MyDollarFormat" is the name of the function we are declaring. Be sure to choose a meaningful name for your custom function and don't use any ColdFusion reserved words (like the names of existing built-in Coldfusion Functions). Next, in parentheses, we can define any values we expect to be passed to our function. In our example, our custom function will expect one value to be passed to the function, which will be assigned to the variable "money_string". This variable is created as a local variable so only ColdFusion code within our custom function will have access to it. To finish the function definition, we use curly braces to define where code will begin and end within the function. Finally, any functions we declare must call the "return()" function. The "return" keyword is unique to custom functions, and is used for returning values from the custom function to the caller. The value returned from a custom function can be used in an expression or in a value assignment, just like the built-in ColdFusion functions.
In our example, we are going to transform the value passed in, then return the result of our transformation. I like the built-in DollarFormat function, but it is rather limiting. It always returns a value with 2 decimal values and a dollar sign preceding the value. That's all fine and dandy, but perhaps we need to code an application where we need to format a money value with no decimal places? Well, we can take care of this by first dollarformatting the value, then using the function RemoveChars to strip the decimal value before returning the formatted string.
Another Example
To really see the power of custom functions, let's take a look at another example of using the custom function MyDollarFormat. On the fly, we want to format 3 values before displaying them.
<cfset value1="1000">
<cfset value2="2000">
<cfset value3="3000">
<cfoutput>
#RemoveChars(DollarFormat(value1),Len(DollarFormat(value1))-3,3)#<br>
#RemoveChars(DollarFormat(value2),Len(DollarFormat(value2))-3,3)#<br>
#RemoveChars(DollarFormat(value3),Len(DollarFormat(value3))-3,3)#<br>
</cfoutput>
Ugh. Let's implement a custom function to clean up this code a bit. Once we encapsulate our formatting logic into a custom function, our code used in displaying values will be much easier to read, and if we need to make an update to the way we are formatting money values, we only have to make the change in one place on this page.
<!--- Declare custom functions for this page --->
<cfscript>
function MyDollarFormat(money_string){
money_string = DollarFormat(money_string);
money_string = RemoveChars(money_string, Len(money_string)-3, 3 );
return(money_string);
}
</cfscript>
<!---Initialize values for this page --->
<cfset value1="1000">
<cfset value2="2000">
<cfset value3="3000">
<!--- Start Presentation/Output --->
<cfoutput>
#MyDollarFormat(value1)#<br>
#MyDollarFormat(value2)#<br>
#MyDollarFormat(value3)#<br>
</cfoutput>
Including Custom Function Libraries in your Application
That's an improvement. Now we can clearly see that we are using a custom function to format our output, and clearly see what values are being formatted for display. We can go one step further To make this code look even cleaner, we can move our custom functions to another ColdFusion template called "functions.cfm" and use a cfinclude at the top of our example to load all custom functions defined in our custom function template.
Functions.cfm
<!--- Custom Functions For Application XYZ --->
<cfscript>
function MyDollarFormat(money_string){
money_string = DollarFormat(money_string);
money_string = RemoveChars(money_string, Len(money_string)-3, 3 );
return(money_string);
}
</cfscript>
Example.cfm
<!--- Include required custom functions not defined in application.cfm --->
<cfinclude template="functions.cfm">
<!---Initialize values for this page--->
<cfset value1="1000">
<cfset value2="2000">
<cfset value3="3000">
<!--- Start Presentation/Output --->
<cfoutput>
#MyDollarFormat(value1)#<br>
#MyDollarFormat(value2)#<br>
#MyDollarFormat(value3)#<br>
</cfoutput>
This way, ColdFusion developers can create their own libraries of custom functions for use in their applications.
For more information on custom functions, see the ColdFusion 5.0 developer documentation. You can also download useful pre-defined custom function libraries from www.cflib.org.
