A More Complete CFC

Listing 23.22 shows a slightly more complex variation on the FilmSearchCFC component created in Listing 23.17. The idea behind this CFC is to provide not only a search facility, but also a way to get and display detailed information about films. To reflect this expanded role, I'll call this version FilmDataCFC instead of FilmSearchCFC.

CFCs as Collections of Functions

In addition to the listFilms() method, Listing 23.22 also includes a new method, getFilmData(), which takes a film's ID number as input and returns a structure containing the film's title, summary, and actors. You can think of this CFC as a collection of conceptually related functions, since both methods are about data retrieval pertaining to records in the Films database table. In a big-picture way, this is what many CFCs are all about: collecting related functionality into a single bundle.

Also, this listing uses the hint attribute in the <cfcomponent> tag and each of the <cffunction> and <cfargument> tags to allow the component to be self-documenting.

NOTE

In fact, once you create a CFC, you can view automatically generated documentation for it by visiting the .cfc file with your browser. For details, see Figure 23.11 in the "Exploring CFCs in Dreamweaver" section, later in this chapter.

Figure 23.11. ColdFusion MX 7 will generate an automatic reference page for any CFC.

Listing 23.22. FilmDataCFC1.cfcProviding Descriptive Information about Methods

 <!---   Filename: FilmDataCFC1.cfc  Author: Nate Weiss (NMW)  Purpose: Creates the FilmDataCFC1 ColdFusion Component, which provides  search and data retrieval services for films in the ows database. ---> <!--- The <CFCOMPONENT> block defines the CFC ---> <!--- The filename of this file determines the CFC's name ---> <cfcomponent   hint="Provides a simple interface for searching for and getting detailed   information about films in the Orange Whip Studios database."  output="false">   <!--- ListFilms() method --->   <cffunction name="listFilms" returnType="query"  hint="Returns a query object containing film information." output="false">       <!--- Optional SearchString argument --->      <cfargument name="searchString" type="string" required="No"     hint="Optional search criteria; if not given, all films are returned.">       <!--- Optional SearchString argument --->      <cfargument name="actorID" type="numeric" required="No"     hint="Allows searching for films by actor.">       <!--- var scope variables --->     <cfset var getFilms = "">     <!--- Run the query --->      <cfquery name="getFilms" datasource="ows">      SELECT FilmID, MovieTitle FROM Films      WHERE 0=0      <!--- If a search string has been specified --->      <cfif isDefined("ARGUMENTS.searchString")>      AND (MovieTitle LIKE '%#ARGUMENTS.searchString#%'      OR Summary LIKE '%#ARGUMENTS.searchString#%')      </cfif>        <!--- If an actor's name has been specified --->      <cfif isDefined("ARGUMENTS.actorID")>      AND FilmID IN      (SELECT FilmID FROM FilmsActors      WHERE ActorID = #ARGUMENTS.actorID#)      </cfif>      ORDER BY MovieTitle     </cfquery>       <!--- Return the query results --->      <cfreturn getFilms>   </cffunction>       <!--- GetFilmData() method --->   <cffunction name="getFilmData" returnType="struct" output="false"   hint="Returns structured information about the specified film.">     <!--- FilmID argument --->     <cfargument name="filmID" type="numeric" required="Yes"     hint="The film that you want information about.">     <!--- This is what this method originally returns --->      <!--- The var keyword makes it local to the method --->     <cfset var filmData = structNew()>     <cfset var getFilm = "">     <cfset var getActors = "">     <cfset filmData.filmID = ARGUMENTS.filmID>       <!--- Select data about the film from the database --->     <cfquery name="getFilm" datasource="ows">     SELECT MovieTitle, Summary FROM Films     WHERE FilmID = #ARGUMENTS.filmID#     </cfquery>       <!--- Populate the FilmData structure with film info --->     <cfset filmData.movieTitle = getFilm.MovieTitle>     <cfset filmData.summary = getFilm.Summary>       <!--- Run second query to get actor information --->     <cfquery name="getActors" datasource="ows">     SELECT ActorID, NameFirst, NameLast      FROM Actors     WHERE ActorID IN     (SELECT ActorID FROM FilmsActors     WHERE FilmID = #ARGUMENTS.filmID#)     </cfquery>       <!--- Make the GetActors query results part of the returned structure --->     <cfset filmData.actorsQuery = getActors>     <!--- Return the final structure --->      <cfreturn FilmData>  </cffunction> </cfcomponent> 

TIP

As the number of methods provided by each CFC increases, you will want to have some way of keeping track of them. Dreamweaver MX addresses this need by allowing you to explore the methods and arguments for each CFC in the Components tree. See the "Exploring CFCs in Dreamweaver MX" section, later in this chapter.

TIP

You can use the Create Component dialog in Dreamweaver MX to create the basic skeleton of <cfcomponent> and related tags. See the "Using the Create Component Dialog" section, later in this chapter.

The listFilms() method was in the last version, but I've adapted it slightly here. It now accepts two optional arguments, searchCriteria and actorName, which can filter the returned query object based on keywords or the name of an actor.

Using the FilmData CFC

The code in Listing 23.22 creates two methods: the listFilms() method can be used to display a list of films, and the getFilmData() method can be used to display detailed information about a particular film. The next two listings show how you can use these methods together to create a simple film-browsing interface.

Listing 23.23 uses the listFilms() method to display a list of films. This isn't much different from the first listing that used the FilmSearchCFC component (Listing 23.18), as shown in Figure 23.7. The only real difference is each film is now presented as a link to a detail page, where the details about the selected film will be shown.

Listing 23.23. UsingFilmDataCFC1.cfmUsing a CFC in a Master-Detail Data Interface

 <!---   Filename: UsingFilmDataCFC1.cfm  Author: Nate Weiss (NMW)  Purpose: Uses the FilmDataCFC component to display a list of films ---> <html> <head><title>Using FilmDataCFC</title></head> <body> <h3>Orange Whip Studios Films</h3> <!--- Invoke the ListFilms() method of the FilmSearchComponent ---> <cfinvoke component="FilmDataCFC1" method="listFilms"  returnVariable="filmsQuery">   <cfif isDefined("url.actorID") and isNumeric(url.actorID)>     <cfinvokeargument name="actorID" value="#url.actorID#">   </cfif> </cfinvoke> <!--- Now output the list of films ---> <cfoutput query="filmsQuery">  <a href="UsingFilmDataCFC1_Detail.cfm?FilmID=#FilmID#">#MovieTitle#</a><br> </cfoutput>  </body> </html> 

Listing 23.24 is the detail page a user gets if they click one of the links created by Listing 23.23. It simply calls the getFilmData() method exposed by the FilmDataCFC1 component, then displays the information using an ordinary <cfoutput> block (Figure 23.9).

Listing 23.24. UsingFilmDataCFC1_Detail.cfmCreating the Film Details Page

 <!---   Filename: UsingFilmDataCFC1_Detail.cfm  Author: Nate Weiss (NMW)  Purpose: Uses the FilmDataCFC component to display one film ---> <html> <head><title>Using FilmDataCFC</title></head> <body> <!--- We need to have a FilmID parameter in the URL ---> <cfparam name="URL.filmID" type="numeric"> <!--- Call the GetFilmData() method of the FilmDataCFC1 component ---> <cfinvoke component="FilmDataCFC1" method="getFilmData"  film  returnVariable="filmData"> <!--- Produce the simple film display --->  <cfoutput>  <h3>#filmData.MovieTitle#</h3>  <p>#filmData.Summary#</p>    <!--- Include a list of actors --->  <p><b>Starring:</b>  <ul style="margin-top:2px">  <cfloop query="filmData.ActorsQuery">  <li>  <a   href="UsingFilmDataCFC1.cfm?actorID=#actorID#"  title="Click for films this actor stars in.">#NameFirst# #NameLast#</a>  </li>  </cfloop>  </ul> </cfoutput>    </body> </html> 

Figure 23.9. The GetFilmData() method can be used to produce a page such as this.

Note that the <cfloop> tag in this listing uses filmData.ActorsQuery as its query attribute. The filmData variable is a structure returned by the getFilmData() method created in Listing 23.22. If you look back at that listing, you will find that getFilmData() returns a structure. The structure contains simple string properties such as movieTitle and summary, but it also contains a property called actorsQuery, which is a query result set object returned by a <cfquery> tag. Because the actorsQuery properties contains a query object, it can be used as the query attribute of a <cfloop> (or, for that matter, of <cfmail>, <cfchartseries>, or any other tag that accepts a query object).

NOTE

The getFilmData() method demonstrates that although component methods can only return a single return value, you can easily have that return value be a structure that contains as much information as you need.

The result is a set of pages that lets the user browse through films, using the actors' names as a way to get from film to film. When a user first visits Listing 23.23, a simple list of films appears. When the user clicks a film's title, they are brought to Listing 23.24, which displays details about the selected film, including a list of actors. The user can click the actors' names, which sends them back to Listing 23.23. This time, though, the selected actor's ID number is passed to the listFilms() method, which means that only that actor's films are shown. The user can click any of those films to see the other actors in the selected film, and so on.

Separating Logic from Presentation

As you saw in the last three listings, it's relatively easy to create a CFC and use its methods to display data, perhaps to create some sort of master-detail interface. The process is basically to first create the CFC, then create a normal ColdFusion page to interact with each of the methods.

When used in this fashion, the CFC is a container for logic (such as extraction of information from a database), leaving the normal ColdFusion pages to deal only with presentation of information. Many developers find it's smart to keep a clean separation of logic and presentation while coding.

This is especially true in a team environment, where different people are working on the logic and the presentation. By keeping your interactions within databases and other logic packaged in CFCs, you can shield the people working on the presentation from the guts of your application. They can focus on making the presentation as attractive and functional as possible, without needing to know any CFML other than <cfinvoke> and <cfoutput>. And they can easily bring up the automatically generated documentation pages for each component to stay up to date on the methods each component provides.

Accessing a CFC via a URL

You have seen how to use CFC methods in your .cfm pages using the <cfinvoke> and <cfobject> tags. It's also possible to access methods directly with a Web browser. That is, if you place a .cfc file in a location that is accessible via a URL, people can use the component's methods by visiting that URL directly.

NOTE

I recommend that you use CFCs by invoking their methods within a .cfm page (using <cfinvoke> or the <cfscript> method syntax), as you have seen already, rather than having browsers visit the CFC's methods directly. This keeps the separation of functionality and presentation clean. If you do decide to have your CFCs accessed directly via a URL, keep the parts of the code that output HTML in separate methods, as the example in this section does.

Visiting the Correct URL

Assuming you installed ColdFusion on your local machine and are saving this chapter's listings in the ows/23 folder within your Web server's document root, the URL to access a component called FilmDataCFC2 would be:

 http://localhost:8500/ows/23/FilmDataCFC2.cfc 

If you visit this URL with your browser, you will get the automatically generated documentation page for the component. (You will be asked for a password before the documentation page will appear; use your ColdFusion Administrator or RDS password).

To use one of the component's methods, just add a URL parameter named method, where the value of the parameter is the name of the method you want to call. For instance, to use the method called ProduceFilmListHTML, you would visit this URL with your browser:

 http://localhost:8500/ows/23/FilmDataCFC2.cfc?method=ProduceFilmListHTML 

NOTE

It is only possible to access a method via a URL if the <cffunction> block that creates the method contains an access="remote" attribute. If you try to use the URL to access a method that has a different access level, ColdFusion will display an error message.

When calling a method via the URL, you can supply values for the method's arguments by including the arguments as name-value pairs in the URL. So, to call the produceFilmHTML method, supplying a value of 3 to the method's filmID argument, you would use this URL:

 http://localhost:8500/ows/23/FilmDataCFC2.cfc?method=produceFilmHTML&filmID=3 

To provide values for multiple arguments, just provide the appropriate number of name-value pairs, always using the name of the argument on the left side of the equals (=) sign and the value of the argument on the right side of the equals sign.

NOTE

If the value of the argument might contain special characters such as spaces or slashes, you need to escape the value with ColdFusion's URLEncodedFormat() function. This is the case for any URL parameter, not just for CFCs. In fact, it's the case for any Web application environment, not just ColdFusion.

NOTE

This is a bit of an advanced topic, but If you need to provide non-simple arguments such as arrays or structures, you can do so by creating a structure that contains all of your arguments (similar to creating a structure to pass to the attributeCollection attribute of the <cfmodule> tag, discussed earlier in this chapter), using the <cfwddx> tag to convert the structure to a WDDX packet, then passing the packet as a single URL parameter called argumentCollection. Or, if you are accessing the CFC via a form, you can provide such a packet as a form field named argumentCollection. See Appendix B, "ColdFusion Function Reference," for details about <cfwddx>.

Creating Methods That Generate HTML

Just because it's possible to access a method with your browser doesn't mean the browser will understand what to do with the result. For instance, if you look at the FilmDataCFC1 component from Listing 23.22, one of the methods returns a query and the other returns a structure. These are ColdFusion concepts; no browser is going to understand what to do with them.

For a CFC to be able to do anything meaningful if accessed via a URL, you must make sure that any methods accessed in this way return HTML that the browser can understand. The most straightforward way to do this is to add additional methods to your CFC that produce the appropriate HTML. Internally, these methods can call the CFC's other methods to retrieve data or perform other processing. To make sure that only the HTML-generating methods are accessible via a URL, only those methods should have an access="remote" attribute.

Listing 23.25 is a revised version of the FilmDataCFC1 component from Listing 23.22. This version adds two new methods called produceFilmListHTML() and produceFilmHTML(). These methods basically contain the same code and produce the same result as Listing 23.23 and Listing 23.24, respectively. In other words, the component now takes care of both logic and presentation.

Listing 23.25. FilmDataCFC2.cfcAdding Methods That Generate HTML

 <!---   Filename: FilmDataCFC2.cfc  Author: Nate Weiss (NMW)  Purpose: Creates the FilmDataCFC2 ColdFusion Component, which provides  search and data retrieval services for films in the ows database. ---> <!--- The <CFCOMPONENT> block defines the CFC ---> <!--- The filename of this file determines the CFC's name ---> <cfcomponent   hint="Provides a simple interface for searching for and getting detailed   information about films in the Orange Whip Studios database."  output="false">   <!--- ListFilms() method --->   <cffunction name="listFilms" returnType="query"  hint="Returns a query object containing film information." output="false">       <!--- Optional SearchString argument --->      <cfargument name="searchString" type="string" required="No"     hint="Optional search criteria; if not given, all films are returned.">       <!--- Optional SearchString argument --->      <cfargument name="actorID" type="numeric" required="No"     hint="Allows searching for films by actor.">       <!--- var scope variables --->     <cfset var getFilms = "">     <!--- Run the query --->      <cfquery name="getFilms" datasource="ows">      SELECT FilmID, MovieTitle FROM Films      WHERE 0=0      <!--- If a search string has been specified --->      <cfif isDefined("ARGUMENTS.searchString")>      AND (MovieTitle LIKE '%#ARGUMENTS.searchString#%'      OR Summary LIKE '%#ARGUMENTS.searchString#%')      </cfif>        <!--- If an actor's name has been specified --->      <cfif isDefined("ARGUMENTS.actorID")>      AND FilmID IN      (SELECT FilmID FROM FilmsActors      WHERE ActorID = #ARGUMENTS.actorID#)      </cfif>      ORDER BY MovieTitle     </cfquery>       <!--- Return the query results --->      <cfreturn getFilms>   </cffunction>       <!--- GetFilmData() method --->   <cffunction name="getFilmData" returnType="struct" output="false"   hint="Returns structured information about the specified film.">     <!--- FilmID argument --->     <cfargument name="filmID" type="numeric" required="Yes"     hint="The film that you want information about.">     <!--- This is what this method originally returns --->      <!--- The var keyword makes it local to the method --->     <cfset var filmData = structNew()>     <cfset var getFilm = "">     <cfset var getActors = "">     <cfset filmData.filmID = ARGUMENTS.filmID>       <!--- Select data about the film from the database --->     <cfquery name="getFilm" datasource="ows">     SELECT MovieTitle, Summary FROM Films     WHERE FilmID = #ARGUMENTS.filmID#     </cfquery>       <!--- Populate the FilmData structure with film info --->     <cfset filmData.movieTitle = getFilm.MovieTitle>     <cfset filmData.summary = getFilm.Summary>       <!--- Run second query to get actor information --->     <cfquery name="getActors" datasource="ows">     SELECT ActorID, NameFirst, NameLast      FROM Actors     WHERE ActorID IN     (SELECT ActorID FROM FilmsActors     WHERE FilmID = #ARGUMENTS.filmID#)     </cfquery>       <!--- Make the GetActors query results part of the returned structure --->     <cfset filmData.actorsQuery = getActors>     <!--- Return the final structure --->      <cfreturn FilmData>  </cffunction>     <!--- ProduceFilmListHTML() method --->   <cffunction name="produceFilmListHTML" access="remote" output="true"   returntype="void" hint="Produces a simple HTML display">       <!--- This variable is local to only to this function --->     <cfset var filmsQuery = "">     <cfset var actorData = "">     <!--- Call the ListFilms() method to get data about all films--->     <!--- Pass along any arguments that were passed to this method --->     <cfinvoke method="listFilms" returnVariable="filmsQuery"     argumentCollection="#ARGUMENTS#">       <!--- Begin displaying output --->     <cfoutput>     <!--- If an ActorID was provided as an argument, then we are --->     <!--- only displaying films that star the specified actor --->     <cfif isDefined("ARGUMENTS.actorID")>       <cfset actorData = getFilmData(filmsQuery.FilmID).actorsQuery>       <h3>Films Starring #actorData.NameFirst# #actorData.NameLast#</h3>       <p><a href="FilmDataCFC2.cfc?method=produceFilmListHTML">       [List Of All Films]</a></p>     <!--- Otherwise, all Orange Whip films are being displayed --->      <cfelse>       <h3>Orange Whip Studios Films</h3>     </cfif>     <!--- For each film, display the title as a link --->     <!--- to this component's ProduceFilmHTML() method --->     <cfloop query="filmsQuery">     <a href="FilmDataCFC2.cfc?method=produceFilmHTML&FilmID=#FilmID#">     #MovieTitle#</a><br>     </cfloop>     </cfoutput>    </cffunction>     <!--- ProduceFilmHTML() method --->   <cffunction name="produceFilmHTML" access="remote" output="true"   returntype="void" hint="Produces a simple HTML display">     <!--- FilmID argument --->     <cfargument name="filmID" type="numeric" required="Yes"     hint="The ID number of the film to display information about">     <!--- Call the GetFilmData() method to get basic film information --->      <cfset var filmData = getFilmData(ARGUMENTS.filmID)>     <!--- Produce the simple film display --->      <cfoutput>     <h3>#filmData.MovieTitle#</h3>     <p>#filmData.Summary#</p>     <!--- Include a list of actors --->     <p><b>Starring:</b>     <ul style="margin-top:2px">     <cfloop query="FilmData.ActorsQuery">     <li>     <a href="FilmDataCFC2.cfc?method=produceFilmListHTML&ActorID=#ActorID#">     #NameFirst# #NameLast#</a>     </li>     </cfloop>     </ul>     </cfoutput>   </cffunction> </cfcomponent> 

Within the produceFilmListHTML() method, the component's own listFilms() method retrieves a list of films. Then an <cfoutput> block generates the HTML that should be returned to the browser. This <cfoutput> code is fairly similar to the code after the <cfinvoke> in Listing 23.23. The main difference is that the href attributes of the links that this code generates point to the produceFilmHTML() method of this same component instead of to a normal ColdFusion page. That is, the HTML generated by this method contains links that will execute other methods of the same component.

NOTE

Look at the argumentCollection="#ARGUMENTS#" attribute used in the <cfinvoke> tag in this listing. Any arguments passed to the produceFilmListHTML() method will be passed along to the listFilms() method as it is invoked. You can use this syntax whenever you want to call a method within another method and want the nested method to receive the same arguments as the outer method.

NOTE

Another interesting thing about this <cfinvoke> tag: it doesn't include a component attribute. Normally, component is a required attribute, but you can leave it out if you are using <cfinvoke> within another method. ColdFusion assumes that you are referring to another method within the same component.

The code for the second new method, produceFilmHTML(), works similarly. Again, this new method calls one of the nonremote methods, getFilmData(), to obtain the information it needs to display. For variety's sake, getFilmData() is called via the <cfscript> syntax, rather than the <cfinvoke> tag.

NOTE

In general, methods that generate HTML or other output with <cfoutput> should not also produce a return value. In other words, you generally shouldn't use <cfoutput> and <cfreturn> within the same method.

Now that you've completed this component, you can visit it using the following URL:

 http://localhost:8500/ows/23/FilmDataCFC2.cfc?method=ProduceFilmListHTML 

The result for the user is the same master-detail film-browsing interface created with Listings 23.23 and 23.24. The only difference is that the CFC is doing all the work on its own, rather than needing separate .cfm files to invoke it. As far as the user is concerned, the only difference is the .cfc extension in the URL.

NOTE

All of the methods, including the non-Remote ones (listFilms() and getFilmData()), are still available for use within normal ColdFusion pages via <cfinvoke> or <cfobject>.

Other Ways of Separating CFC Logic from Presentation

Listing 23.25 contains two logic methods and two presentation methods. Although only the presentation methods can be accessed directly with a Web browser (because of the access="remote" attribute), they are all included in the same CFC file.

If you wanted, you could create a separate CFC for the presentation methods. You would just use the <cfinvoke> tag within the presentation CFC to call the logic methods.

Another option is to store the presentation methods in their own .cfc file, adding an extends attribute that specifies the name of the logic CFC. This would cause the presentation CFC to inherit the methods from the logic CFC so it could use them internally, as shown in Listing 23.25. Component inheritance and a complete discussion of the extends attribute are beyond the scope of this chapter. For details, consult the ColdFusion documentation or this book's companion volume, Advanced Macromedia ColdFusion MX 7 Application Development.

Accessing a CFC via a Form

It is also possible to access a method directly from a browser using a form. Conceptually, this is very similar to accessing a method via a URL, as discussed in the previous section, "Accessing a CFC via a URL." Just use the URL for the .cfc file as the form's action, along with the desired method name. Then add form fields for each argument that you want to pass to the method when the form is submitted. For example, the following snippet would create a simple search form, which, when submitted, would cause a list of matching films to appear.

 <cfform action="FilmDataCFC2.cfc?method=ProduceFilmListHTML">  <input name="searchString">  <input type="Submit" value="Search"> </cfform> 

NOTE

Again, the method must use access="remote" in its <cffunction> tag. Otherwise, it can't be accessed directly over the Internet via a Form or a URL.

Exploring CFCs in Dreamweaver

Once you've written your CFCs, they become a part of Macromedia Dreamweaver. You can explore each CFC's hints and methods, display automatic documentation for each CFC, and drag and drop methods into your ColdFusion pages. These features make it even easier for you and your team to reuse code with CFCs.

The heart of the Dreamweaver-CFC integration is the Components tab in the Application panel, which is displayed by default if you chose the HomeSite/Coder interface while you were installing Dreamweaver. If you don't see the Application panel, select Window > Components from the main menu.

TIP

As a shortcut, you can use Ctrl-F7 (or equivalent) to show the Application panel.

NOTE

If the tabs in the Application panel are dimmed (i.e., disabled), open a file that is associated with a site that uses ColdFusion as the Application Server type. You've probably already done this for the ows folder in your Web server's document root, so just open any of the .cfm files within ows. That should enable the Application panel.

Viewing All Your CFCs

With the Application panel expanded, click the Components tab. You will notice a drop-down list at the top of the tab, with choices for CF Components or Web Services. Make sure CF Components is selected.

You should now see a tree with items for each folder on your Web server that contains a .cfc file. For instance, you should see an item for ows.23 (the 23 folder within the ows folder); this will contain the CFCs created in this chapter.

NOTE

I am assuming that you have copied all the example files for this chapter from the CD-ROM to the /ows/23 folder win your Web server's document root. If not, do so nowor keep in mind that only the .cfc files that are actually present on your server will be shown in the tree in Dreamweaver.

Go ahead and expand the ows.23 item in the tree. The CFCs for this chapter, including the FilmSearchCFC, FilmDataCFC, and FilmRotationCFC components, will display as nested items in the tree. You can expand each CFC to reveal its methods, and you can expand each method to reveal its input arguments (Figure 23.10).

Figure 23.10. Dreamweaver makes it easy to keep track of your CFCs and their methods.

NOTE

If you add to or change a CFC, click the Refresh button at the top right corner of the Components tab to make the tree reflect your changes.

NOTE

ColdFusion and Dreamweaver refer to the ability to display this kind of information about components as component introspection. The fact that the server can look into the component file to learn about its methods, return values, and arguments is a key feature of the new CFC framework. Component introspection makes many things possible, including the tight Dreamweaver integration you are seeing here, the Flash integration you will learn about in Chapter 26, and ColdFusion's ability to automatically expose your CFCs as Web Services.

Jumping to CFC Code from the Tree

Once you have the Components tree showing in the Application tab (see the previous section, "Viewing All of Your CFCs"), you can double-click the items in the tree to open the corresponding .cfc file.

If you double-click

• a component (like the FilmDataCFC item), Dreamweaver will open up the .cfc file, ready for your edits.

• a method within a component (like getFilmData or listFilms), Dreamweaver will open the file, then scroll down and highlight the corresponding <cffunction> block.

• an argument within a method (like searchString or filmID), Dreamweaver will open the file and scroll down to the corresponding <cfargument> tag.

Inserting <cfinvoke> Tags via Drag and Drop

If you're working on a ColdFusion page and want to call one of your CFC's methods, Dreamweaver can automatically write the appropriate <cfinvoke> code for you. Just click the method in the Components tree (see Figure 23.10), then drag it to the appropriate spot in your code. When you release the mouse, a <cfinvoke> tag will be added to your code with the component, method, and other attributes already filled in for you. In addition, a <cfinvokeargument> tag will be added for each of the method's required arguments. This can be a real time saver.

TIP

You can insert the same code by right-clicking the method and choosing Insert Code from the contextual menu.

Viewing CFC Details

To get more information about an item in the Components tree, right-click the item, then select Get Details from the contextual menu. A message box will appear, displaying detailed information about the component, method, or argument.

Viewing CFC Documentation

One of the coolest CFC features in ColdFusion is the ability to generate a documentation page automatically for each of your components. You can use the page as a live reference guide to the CFC. (If you are familiar with Java, this is analogous to a javadoc page).

To view the automatic reference page for a component, right-click the component (or any of its methods or arguments) in the Components tree and select Get Description from the context menu. Dreamweaver will launch your browser with the documentation page showing. For instance, the generated documentation page for the FilmDataCFC component is shown in Figure 23.11.

Viewing CFC Documentation without Dreamweaver

You don't have to use Dreamweaver to generate the documentation page for a CFC. You can view the documentation page at any time by just navigating your browser to the URL for the .cfc file. For instance, assuming you have installed ColdFusion on your local machine, you can get to the documentation page at http://localhost:8500/ows/23/FilmDataCFC2.cfc

TIP

Of course, once you have the generated documentation page open in your browser, you can always use your browser's File > Save As command to save the HTML file to some permanent location on your local hard drive. That way, you can view or print the documentation even when you can't connect to the ColdFusion server.

Using the Create Component Dialog

Wizards aren't for everyone, but if you like them, Dreamweaver provides a very nice Create Component dialog box that you can use to create new .cfc files. This wizard-style interface makes it easy to design a new CFC. You just fill in the blanks about your new component's name, hints, methods (functions), arguments, and so on.

To launch the Create Component dialog, click the button marked with a plus sign (+) at the top of the Components tab in the Application panel. Or you can right-click anywhere in the Components tab and select Create New CFC from the contextual menu. The Create Component dialog will appear (Figure 23.12). Just fill in the desired blanks on each of the various pages. Except for the component's name and directory, you can leave any of the other items blank.

Figure 23.12. The Create Component dialog can make it easier to design a new CFC.

When you click OK, Dreamweaver will generate the appropriate skeleton of <cfcomponent>, <cffunction>, <cfargument>, and <cfreturn> tags for you. All that remains is to add the appropriate method code to each of the <cffunction> blocks.