Accessibility
Home / Developer Center / Dreamweaver Developer Center /

Dreamweaver Article

Icon or Spacer Icon or Spacer Icon or Spacer
Adrian Senior

Adrian Senior
http://www.communitymx.com/

 
Creating User-Defined Functions for ColdFusion MX in Dreamweaver MX

In this tutorial, you'll learn how to create a simple user-defined Function (UDF) for ColdFusion MX in Dreamweaver MX that will provide an easy way to access data instead rewriting code each time you need to access data source information. Specifically, you will write the information from the UDF to a document by requesting a particular records ID, using a static fixed option and by calling the ID from a user-defined form.

dw_udfs.zip (14K)


Setting Up DreamweaverMX for ColdFusion
In this section, you'll set up Dreamweaver MX and ColdFusion Server, your datasource, and the tags you'll need to create the UDF.

  1. Define a ColdFusion site in Dreamweaver MX.
  2. If you want to use the sample files you downloaded above, create a data source named devnetudf for udf.mdb in ColdFusion Administrator.
  3. Create a new CFML page and save it as view.cfm within /cf_webroot/dw_udfs/ (create the folder if it does not yet exist). Unzip the sample files and place the folders /example and /include within /cf_webroot/dw_udfs/ as well.
  4. In Dreamweaver, select the CFML Advanced tab, and then the More Tags (the last option in the CFML Advanced tab) option.
  5. Expand the CFML Tags folder and select ColdFusion MX Components (see figure 1).
 

More Tags under the CFML Advanced Tab

 
  1. Select cffunction from the list and click Insert. The Tag Editor dialogue box appears. Name the function retrieveit (see Fig. 2). Click OK.
 
Adding and naming the function
 

Change to Code View in Dreamweaver MX and see the ccffunction tag that Dreamweaver inserted into view.cfm.

  1. Place your cursor between the beginning and end tags for cffunction and press Enter twice to insert extra space. Your code should look like the following:
      <cffunction name="retrieveit" output="false">
      </cffunction>
  1. Put your cursor between the cffunction tag and press return so that you are on a new line (you will repeat steps 4-7 for the cfargument tag). Complete the dialogue box as shown in Fig 3 (naming the cfargument tag ID, selecting numeric Type, and checking the required box).. Be sure that you press return after the cfargument tag to begin a new line.

 

Adding the cfargument tag and properties
 

The argument will pass the ID field (a number) into the UDF from our page, and requires a value.

Next we will create a variable. We 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. We can leave our variable empty as it will be populated from the query run from the UDF.

  1. Select the CFML Basic tab in Dreamweaver. Click set.
    This inserts an empty cfset tag for you. Name the variable GetTeams. Leave its value empty, as shown below.

    <cfset GetTeams = "">

    The variable hold the UDF query results.

Creating the UDF with DreamweaverMX
Next you will build the query.

  1. Place your cursor below the cfset tag, but before the closing cffunction tag.
  2. Select Query (looks like a small barrel) from the CFML Basic tab and specify the information, as shown in figure 4.

 

a=Adding a query
 
Select the Persistent Queries option and complete as shown in Fig 5.
 
Persisting a query
 
The Cached Within feature allows you to specify a time during which ColdFusion server will save the query results in memory. In this example, the time spans are shown as all zeros, which represent days, hours, minutes and seconds, (from left to right). Thus, ColdFusion server will execute the query every time a user reqeusts a page which has the query. You can specify the time during which query lives in memory by changing the hours to a 1, which would direct ColdFusion server to save the query in memory for one hour.

Now you will return to the Dreamweaver Tag Chooser to finish adding required ColdFusion tags for building the UDF.

  1. Click the CFML Advanced tab an then the More Tags option.
  2. Select the cfreturn tag.
  3. Complete the cfreturn tag in the Dreamweaver Code View as shown below:

    <cfreturn GetTeams.Teams>

    The cfreturn tag defines what the UDF will return when a page passes information to it. The cfreturn requires you to specify information from the Teams column that you have from the GetTeams Query; which, in turn is filtered based on the value of the ID that you passed through the cfargument tag.

    The completed UDF should look like the following (note that your code may look different if you changed the Cached Within attribute):

    <cffunction name="retrieveit" output="false">
         <cfargument name="ID" type="numeric" required="true">
           <cfset var GetTeams = "">
           <cfquery name="GetTeams" datasource="devnetudf" 
                cachedwithin="#CreateTimespan(0,0,0,0)#">
              SELECT Teams FROM tbl_info
              WHERE ID = #ARGUMENTS.ID#
           </cfquery>
           <cfreturn GetTeams.Teams>
    </cffunction>

Browsing the UDF
Now you can retrieve data from the UDF very easily. We can call the information statically, as shown below:

<cfoutput>#retrieveit(1)#</cfoutput>

You can also browse static.cfm from your browser (for instance, at http://localhost:8500/dw_udfs/static.cfm). Note that the server name will vary based on your setup.

Likewise, you may you may retrieve data from the database based on a user's form data (where the information comes from a select list form control, named selInfo):

<cfoutput>#retrieveit(form.selInfo)#</cfoutput>

You can browse select.cfm through your browser (for instance, at http://locahost:8500/dw_udfs/select.cfm). The form action goes to result.cfm. The results change based on your selection.

Now that you've completed your UDF, you can copy the code into a separate file and use it as an include. In this way, you can refer to the UDF within your pages with minimal code. Check out my completed sample code download to browse the completed UDF.

This tutorial taught you how to create a UDF from within Dreamweaver MX. Check out DevNet for more information on UDFs.

 


 

About the author
Adrian Senior owns the UK based design agency, Webade, where he has built a strong client base since the company's conception in 1998. Adrian is a member of Team Macromedia and you can find him in the Dreamweaver MX newsgroup on a daily basis.

Before becoming involved with website design and development, Adrian's working life was centered around the Shipyards of the River Mersey and oil production units in the North Sea. He's been married to his wife Janette for 22 years and has two children, Antony aged 20 and Eleanor aged 16.