Creating user-defined functions for ColdFusion 8 in Dreamweaver CS4

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.

Setting up Dreamweaver CS4

In this section, you'll set up Dreamweaver CS4 and ColdFusion Server and the tags you'll need to create the UDF.

1. Define a ColdFusion site in Dreamweaver CS4.

   Note: For more details on how to set up a site in Dreamweaver, see Setting up a Dreamweaver site in Dreamweaver Help or view the video Defining a site.

2. Create a new CFML page and save it as test.cfm within /cf_webroot/dw_udfs/ (create the folder if it does not yet exist).
3. In Dreamweaver, select the Insert > CFML > Advanced tab, and then the More Tags (the last option in the CFML Advanced tab) option.
4. Expand the CFML Tags folder and select Extensibility (see Figure 1).

5. Select cffunction from the list and click Insert. The Tag Editor dialogue box appears. Name the function formatDateTime (see Figure 2). Click OK and then Close.

6. Change to Code View in Dreamweaver CS4 and locate the cffunction tag that Dreamweaver inserted into test.cfm.
7. Place your cursor between the beginning and end tags for cffunction and press Enter twice to insert an extra space. Your code should look like the following:

8. Put your cursor between the cffunction tag and press Enter so that you are on a new line. You will now repeat steps 3 through 6 for the cfargument tag. Complete the dialog box as shown in Figure 3 (name the cfargument tag datetime, selecting Date for Type, and select the Required check box). Be sure that you press Enter after the cfargument tag 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.

9. Select cfsetfrom the Insert/CFML tag list. This inserts an empty cfset tag for you. Name the variable formattedString. Add var before formattedString and after cfset. Then add = "" to keep its value empty, as shown below:

10. As I mentioned at the beginning of this article, ColdFusion has functions to format dates and times. You will use both these functions together to create the result of the UDF. Press the Enter key to add a blank line after the previous cfset and paste in the following code:

This sets the value of formattedString to the combination of two ColdFusion functions: dateFormat and timeFormat. Note that you also add an empty space between these two functions. Both dateFormat and timeFormat allow you to specify format options, but for now you are simply going to use the defaults.

11. Now you need to return this value out of the UDF. Once again return to the CFML Advanced, Extensibility tag list, and this time select CFRETURN. This inserts a blank cfreturn tag. Inside the tag you need to specify the value to return. Enter formattedString. The following snippet shows the complete UDF:

Testing the UDF

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:

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 createDateTime function:

This displays: Santa will pass 24-Dec-08 11:59 PM.

Where to Go Next

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!