22 December 2008
In this tutorial, you'll learn how to create a simple user-defined function (UDF) for ColdFusion 8 in Dreamweaver CS4 that will provide an easy way to format date and time data using one simple function. ColdFusion provides nice time and date formatting, but no way to format both a date and time together. The UDF will solve that problem.
You may wonder why building UDFs is useful at all. UDFs let you take a process, any process really, and collapse it into one simple call. A real-world comparison would be running to the store to get coffee. This process involves multiple steps: getting the car keys, driving to Starbucks, buying the coffee, and driving back home. If you needed to do this multiple times (and who doesn't drink more than one cup of coffee), you would have to repeat the steps multiple times as well. If you could gather these steps into one process, though, called "getCoffee," then you can simplify the process. If this were code, instead of having 5 to 6 lines of code every time you needed to get coffee, you would define the process once (in the UDF) and then simply run
getCoffee() every time you needed it.
In this section, you'll set up Dreamweaver CS4 and ColdFusion Server and the tags you'll need to create the UDF.
cffunctionfrom the list and click Insert. The Tag Editor dialogue box appears. Name the function formatDateTime (see Figure 2). Click OK and then Close.
cffunctiontag that Dreamweaver inserted into test.cfm.
cffunctionand press Enter twice to insert an extra space. Your code should look like the following:
<cffunction name="formatDateTime" output="no" verifyclient="no" securejson="false"> </cffunction>
cffunctiontag and press Enter so that you are on a new line. You will now repeat steps 3 through 6 for the
cfargumenttag. Complete the dialog box as shown in Figure 3 (name the
cfargumenttag datetime, selecting Date for Type, and select the Required check box). Be sure that you press Enter after the
cfargumenttag to begin a new line.
The argument will pass the datetime field (a date and time value) into the UDF from your page, and requires a value.
Next, you will create a variable. You will use the
var keyword to tell ColdFusion that this variable is for this function only. It will be defined as a local variable and will be discarded when you execute the
cffunction tag. You can leave your variable empty as it will be populated from the rest of the code in the UDF.
cfsettag for you. Name the variable formattedString. Add var before formattedString and after cfset. Then add = "" to keep its value empty, as shown below:
<cfset var formattedString = "">
<cfset formattedString = dateFormat(arguments.datetime) & " " & timeFormat(arguments.datetime)>
This sets the value of
formattedString to the combination of two ColdFusion functions:
timeFormat. Note that you also add an empty space between these two functions. Both
timeFormat allow you to specify format options, but for now you are simply going to use the defaults.
cfreturntag. Inside the tag you need to specify the value to return. Enter formattedString. The following snippet shows the complete UDF:
<cffunction name="formatDateTime" output="no" verifyclient="no" securejson="false"> <cfargument name="datetime" type="date" required="yes"> <cfset var formattedString = ""> <cfset formattedString = dateFormat(arguments.datetime) & " " & timeFormat(arguments.datetime)> <cfreturn formattedString> </cffunction>
Now that you've written the UDF, it's time to begin playing with it. Place your cursor after the end of the function and press the Enter key a few times. To call the UDF you just created, you use the same syntax you would for any regular built-in user-defined function. For example:
<cfoutput> #formatDateTime(now())# </cfoutput>
This displays your current date and time (for example, 30-Oct-08 08:45 PM). You can also specify a date and time using the
<cfoutput> Santa will pass #formatDateTime(createDateTime(2008, 12, 24, 23, 59, 59))# </cfoutput>
This displays: Santa will pass 24-Dec-08 11:59 PM.
This article only scratches the surface of what you can do with UDFs. For more information be sure to read the documentation included with ColdFusion 8. For a huge selection of UDFs to use with your own projects, visit the Common Function Library Project, which contains hundreds of ColdFusion UDFs—all free and ready for immediate download!