• Home
• Tutorials
• Forums
• Reference
• Developers
• Advertise
• About Us

User Defined Functions....

I'm always getting asked to place a tutorial on how to work with user-defined functions, I will display a couple of examples; as well as an explanation as to why you should use user-defined functions.

The first example shows a simple way of doing mathematical functions with user-defined functions, let's create a new one:

The first thing we must do is to create the function, you always create user-defined functions within a pair of <cfscript></cfscript> tags, see below:

<cfscript>
      function ProcDif(difference,total)
        {
            x = #difference#;
            y = #difference#/#total#;
            z = round(x + y);
        }
</cfscript>

<cfoutput>
     #ProcDif(20,35)#
     #ProcDif(520,45)#
     #ProcDif(10,85)#
     #ProcDif(40,15)#
</cfoutput>

The beauty of user-defined functions is that it simply needs to be defined only once, then anywhere on your pages you can refer to it and have it process that value automatically. This means that all processing will be that much faster. It also means that when you want to make a change to how the data should be processed, you simply edit the user-defined function within the <cfscript></cfscript> tags.

The next example will demonstrate how you can use user-defined functions to parse through data and display a phone number correctly.
(keep in mind that this example is assuming that all phone numbers in the db are in xxx-xxx-xxxx format. If your numbers not in this format, addtional changes my be required)

The first thing we need to do is query the database for our phone numbers:

<!------------------------------------------------------------------------------
     *************** GET ALL RESERVATIONS ***************
------------------------------------------------------------------------------->
<cfquery name="qGetReservations" datasource="MyDSN" username="MyUserName" password="MyPass">
  select            *
  from              reservations
  order by        reservation_date DESC
</cfquery>

<!------------------------------------------------------------------------------
   *************** GENERATE A PHONE STRUCTURE ***********
------------------------------------------------------------------------------->
This structure simply is being created, not called yet. What you're telling it is that you want to create a variable called "PhoneNumber" and that you require a single value being passed to it. The value will be the phone number you queried above from the database. The way you pass values is as follows:

#CleanedPhoneNumber(qGetReservations.phonenumber)# = qGetReservations.phonenumber being the current phone number for this record count.

So now that you understand the way you pass values, let's continue explaining how it processes it:
<cfscript>
    function CleanedPhoneNumber(number)
        {
            // The first thing we need to do is just have the numbers, this command removes anything that is not shown between the [ ] brackets.
            current_phone = #ReReplaceNoCase(number, '[^0123456789]', '', 'ALL')#;
            //Define the area code, this takes the left 3 characters and specifies them as area code.
            areacode = left(current_phone, 3);
            //Define The First Three, this takes the middle three values starting at position 4 and defines them at the first three numbers of the phone number.
            firstthree = mid(current_phone, 4, 3);
            //Define The Last Three, this takes the last four numbers and defines them as the last four digits of the phone number.
            lastfour = right(current_phone, 4);
            //Define the actual One, this is the final variable that you can customize to export the look you want for the displaying of the phone number.
            phone_number = "(#areacode#)#firstthree#-#lastfour#";
        }
</cfscript>

Now, you can simply do this:

<cfoutput query="qGetReservations">
      #CurrentRow# ) #CleanedPhoneNumber(qGetReservations.phonenumber)#<BR>
</cfoutput>

This will go through and process each individual record and format the phone number correctly.

In closing, user-defined functions allow you to create your own little specifications for the ColdFusion server, they empower you to not only speed up your pages, but also to call the same function numerous times from any page. The user-defined function was introduced in ColdFusion 5.0 and will not run in 4.5 or earlier versions. I you would like more information on user-defined functions, please visit Macromedia's Live Docs (User-Defined Functions) area.

Congratulations, you now have a general understanding of user-defined functions.