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.
My recordset is named rsDirectory and my phone field is named PhoneNo. What changes do I need to make in this script to accommodate my data? Thanks
Following Code is generating an error.
"
I have read the chapter on EDF's in Ben Forta's boo, "ColdFusion MX Web Application Construction Kit", the "Inside ColdFusion MX" book by New Riders publishing, and this tutorial and I still do not understand UDF's.
Up until now I thought I was catching on fast...
Can somebody write another tutorial that does not make use of features which someone who is just learning about UDF's doesn't know about? And please, if you will, include an explanation of how to write UDFs and call them using the