ColdFusion Components

[ LiB ]

Designing your ColdFusion application generally starts when you have a particular problem to solve. For example, maybe you need to build a shopping cart or build a system to take care of your Human Resources information. You have one problem and a solution designed specifically for that problem. However, as your site grows and the functionality becomes more complex, having applications in multiple places that need access to the same data or that need to perform many of the same functions becomes a liability. You end up with more and more processing pages in different locations that all do the same thing. If you need to make a change, you end up having to change multiple locations.

One solution that ColdFusion provides is ColdFusion Components (CFCs). CFCs are files that encapsulate your application's information or functionality into separate files that can be maintained and accessed separately by multiple pages and applications.

For a detailed look at ColdFusion Components, check out Macromedia ColdFusion MX Web Application Construction Kit by Ben Forta et al.

Dreamweaver allows you to build CFCs quite easily by adding them as a document type that you can select from the New File dialog box. When you select Dynamic Page and ColdFusion Component, Dreamweaver opens a new page and inserts the necessary code framework:

 <cfcomponent>     <cffunction name="myFunction" access="public"  returntype="string">         <cfargument name="myArgument" type="string"  required="true">         <cfset myResult="foo">         <cfreturn myResult>     </cffunction> </cfcomponent>

The CFCOMPONENT tag starts the file just like <html> starts an HTML file and indicates that the file is a CFC. Each CFC can contain multiple CFFUNCTION tags, each of which is a method of the component. Each CFFUNCTION can accept one or more arguments that are data passed to the function. It also returns some information that is handed back to the page that called the CFC.

A simple CFC would be one that gets a list of employees from a database and lists them with their departments. To make this interesting, though, the CFC also allows you to pass a variable from a form to limit the search to look for employees in a particular department. This is the CFC you will create in the exercise for this chapter.

Exercise 24.1. Make Sure Your Workstation Is Properly Set Up

You need to have ColdFusion MX installed on your machine, and the service needs to be running. You also need to have a web browser installed and running. You can test this by starting the ColdFusion administrator. In the Administrator, check the Data Sources. You should see that a data source named cfsnippets is installed. It comes with ColdFusion MX when you install it. If you see all that, you are set up correctly.

Set Up Your Site

If you don't have a site set up for ColdFusion, set up one now. If you have a ColdFusion site defined already, you can skip to the next section.

You don't need any supporting files for this exercise. You will create the entire project from scratch, so you don't need to move any files around for this exercise.

Expand the Site Files panel, and choose Site > New Site to open the Site Definition dialog box. In this dialog box, bring the Advanced tab to the front.
For Local Info , set the following:
- Name SearchEmployeeExercise
- Local Root Folder Create a new folder. Call it SearchEmployeeExercise. Set it as your local folder.
For Testing Server, set the following:
- Server Type ColdFusion
- Access Local/Network
- Testing Server Folder Browse to the SearchEmployeeExercise folder.
- URL Prefix http://localhost/SearchEmployeeExercise/.
Click OK to close the Site Definition dialog box. The Site panel now shows your site. Note that the left portion of the panel shows the testing server, not the remote site, which appears when you're working with static sites (unless you have changed your preferences to change the locations of the panels).
When you're working with a dynamic site, Dreamweaver uses the files on the testing server for previewing in the browser. Because you will create everything from scratch, you don't need to move anything around.

Create the ColdFusion Component

Select File > New.
In the Category column, select Dynamic Page, and in the Dynamic Page column, select ColdFusion Component, and click Create.

Your page should look like this:
```
 <cfcomponent>     <cffunction name="myFunction" access="public"  returntype="string">         <cfargument name="myArgument" type="string"  required="true">         <cfset myResult="foo">         <cfreturn myResult>     </cffunction> </cfcomponent> 
```
Save the file as EmployeeDataCFC.cfc in the SearchEmployeeExercise folder.

You now have the basis of the CFC created and ready to modify in Code view. To edit CFCs, you need to stay in Code view.
In the CFFUNCTION tag, change the name of the function to GetEmployeeFunction . You can have multiple functions in one CFC, so naming them with as much information as you can is helpful.
In the CFFUNCTION tag, change the returntype to query from string . This function returns a query that the calling page can use to display.
In the CFARGUMENT tag, change the name to SearchString , and delete the type attribute.
In the CFARGUMENT tag, set the required attribute to No . You want to be able to call the function whether or not an argument is passed from the calling page.
Delete the CFSET tag following the CFARGUMENT.
Change the value of the CFRETURN from the placeholder myResult to SearchEmployees .

You are ready to add the code to actually do something in the CFC now that you have the framework for the tag ready.
Place the insertion point between the CFARGUMENT and the CFRETURN tag. Click the CFQUERY object in the CFML insertion bar.
In the General tab of the Tag Editor for CFQUERY, enter the following:

Query Name SearchEmployees

Data Source cfsnippets

User Name Leave blank

Password Leave blank

SQL SELECT *

FROM employees

ORDER BY LastName

Click OK to close the dialog box.

Your code should look something like this:
```
 <cfcomponent>     <cffunction name="GetEmployeeFunction" access="public"  returntype="query">         <cfargument name="SearchString" required="No"> <cfquery name="SearchEmployees" datasource="cfsnippets"> SELECT * FROM employees ORDER BY LastName </cfquery>         <cfreturn SearchEmployees>     </cffunction> </cfcomponent> 
```
You now have a query that selects everything in the employees table and then returns it to the calling page. This works fine for cases when your user wants to return all the records, but with the CFARGUMENT, the component is set to accept some input to limit that search. You need to add that condition to the query.
Place the cursor after the FROM employees line, and press Enter to create a new line.
Click the CFIF object in the CFML insertion bar.

You need to enter the condition to check for. In this case, you have an argument in CFARGUMENT called arguments.SearchString , and you need to see if it has a value. Enter the following:

arguments.SearchString NEQ ""

You are asking if arguments.SearchString is not equal (NEQ) to nothing. This is the same as asking if it is equal to anything. If it is equal to anything, the CFIF is true, and the code in the CFIF is executed.
Move the cursor to the end of the CFIF and before the /CFIF. Press Enter to create a new line.

On the new line, type

WHERE Department LIKE '%#arguments.SearchString#%'

Save the file.

You have added a WHERE clause to the SQL that limits the search to records in which the Department is like the variable arguments.SearchString , which contains whatever value is passed to the component from the calling page.

Your code should look like this:

 <cfcomponent>     <cffunction name="GetEmployeeFunction" access="public"  returntype="query">         <cfargument name="SearchString" required="No"> <cfquery name="SearchEmployees" datasource="cfsnippets"> SELECT * FROM employees <cfif arguments.SearchString NEQ ""> WHERE Department LIKE '%#arguments.SearchString#%'</cfif> ORDER BY LastName </cfquery>         <cfreturn SearchEmployees>     </cffunction> </cfcomponent>

If you want to, you can reformat it a little to make it easier to read.

Create the Search Employees Page

Now that you have created the CFC that executes the query and returns the result, you need to make the page that calls the CFC.

Create a new ColdFusion page from the New File dialog box. You don't need a CFC, just a regular ColdFusion page. You should be in Design view.
Save the page as searchemployees.cfm .
From the Forms insert bar, insert a form in the form type:

Enter Department:
On the same line, insert a text field from the Forms insert bar. Name the text field department in the Property Inspector. Press Enter to create a new line.
Insert a Submit button on the new line.
Save the file. Your page should look like Figure 24.6.

Figure 24.6. Searchemployees.cfm.
Change the title of the page to Search Employees.
You have the form for the user to enter the department to search. Now you need to invoke the component you built and set up the page so that if it is called without any form input, the component is not called. This is the case when the page is called the first time or from any link directly to the page. However, when the page is called from itself with or without any input, the component is invoked.
Switch to Code view.
Place the cursor at the end of the form tag. Press Enter a few times to give yourself some space to work.
On one of the blank lines, insert a CFIF.
In the CFIF tag, you need to test to see if a form variable is being passed to the page using the IsDefined() function. Type

IsDefined("Form.department")
Place the cursor between the CFIF and the /CFIF tags. Press Enter to give yourself more space.
Open the Application panel group , and bring the Components panel to the front. Select CF Component from the drop-down list at the top left of the panel if it is not showing.
You should see an entry in the panel for SearchEmployeeExercise, as shown in Figure 24.7. Expand the entry to see the CFCs available.

Figure 24.7. The SearchEmployee-Exercise CFC in the Components panel.

Select the query called GetEmployeeFunction(SearchString) in the EmployeeDataCFC in the Components panel. Click the Insert button (the second from the right at the top of the panel) to insert the CFINVOKE into the document.

Your code should look something like this:

 <html> <head> <title>Search Employees</title> <meta http-equiv="Content-Type" content="text/html;  charset=iso-8859-1"> </head> <body> <form name="form1" method="post" action=""> <p>Enter Department:     <input name="department" type="text" id="department"> </p> <p>   <input type="submit" name="Submit" value="Submit"> </p> </form> <cfif IsDefined("Form.department")> <cfinvoke  component="SearchEmployeeExercise.EmployeeDataCFC"  method="GetEmployeeFunction"  returnvariable="GetEmployeeFunctionRet"> </cfinvoke> </cfif> </body> </html>

You need to add the CFARGUMENT to the CFINVOKE tag to specify the name of the variable that is passed to the CFC.

Place the cursor at the end of the CFINVOKE tag, before the /CFINVOKE tag, and type
```
  <cfinvokeargument name="SearchString" value= "#Form.department#">  
```
This sets a value of the contents of the form's department field to the variable SearchString , which is passed to the CFC.
Save the file.

The page is mostly done. Now that you are calling the CFC and passing it the variable SearchString , you need to add a place to display the information that gets returned from the CFC.
Place the cursor after the end of the /CFINVOKE and before the /CFIF tag. Press Enter a few times to give yourself space to work.
Click the CFOUTPUT from the CFML insert bar, and enter GetEmployeeFunctionRet for the query. Remember that this is the name of the return variable from the CFINVOKE tag.
Press Enter to create a new line, and type
```
  <b>#FirstName# #LastName#</b> works in #Department#<br>  
```
This takes the results of the query in the CFC and iterates through the records, printing the first name, last name, and department that are returned.
Save the file.

Test the Application

Now you can test your application. When you preview the searchemployees.cfm file in the browser, you see the page with just the search box and the Submit button. When you call the page for the first time, no form value is defined. The CFIF condition tests and finds nothing, so the CFINVOKE is not called.

Enter nothing in the search box, and click Submit. The CFIF tests to see if a Form.department variable is defined. There is, even though it has no value. Because the variable is present, the CFINVOKE is called in the CFIF.

In the CFC, the CFARGUMENT is checked. The CFC finds that it is unnecessary to have an argument passed in, so the CFQUERY is executed. The CFQUERY has another CFIF that checks to see if the variable SearchString from the CFARGUMENT tag is empty. Because SearchString is empty, the CFIF does not evaluate as true. Therefore, the WHERE clause, which would limit the search to one department, is not executed. The CFQUERY finishes executing and passes that back as a query to the calling page, searchemployees.cfm .

On the calling page, the CFOUTPUT tag iterates through the returned data and prints the names of all the employees.

Now test the page and enter Sales for the department.

The CFIF tests to see if a Form.department variable is defined. Because the variable is present, the CFINVOKE is called in the CFIF.

In the CFC, the CFARGUMENT is checked. The CFC finds that it is unnecessary to have an argument passed in, so the CFQUERY is executed. The CFQUERY has another CFIF that checks to see if the variable SearchString from the CFARGUMENT tag is empty. Because SearchString has the value of Sales , the CFIF evaluates as true. Therefore, the WHERE clause, which limits the search to the one department specified, is executed. The CFQUERY finishes executing and passes that back as a query to the calling page, searchemployees.cfm .

On the calling page, the CFOUTPUT tag iterates through the returned data and prints the names of only the employees in the Sales department.