Introspection

We've been dutifully adding information in our component using the displayname and hint attributes of the <cfcomponent> and <cffunction> tags. Let's take a look now at how those descriptions and all of the CFC's other details can be used for improved documentation and team development.

We mentioned earlier that a CFC has the ability to examine itself and describe its capabilities. You can use the component browser from Dreamweaver (Figure 19.1) to see this in action (as described in depth in the Macromedia ColdFusion MX 7 Web Application Construction Kit). Dreamweaver looks at the definition of the current site for the identity of the ColdFusion server being used. It then makes a request to that ColdFusion server for a listing of all of the components available.

Figure 19.1. The component browser in Dreamweaver.

Within the Actors component, you can see its methods listed in a descriptive mannerreturnType methodName (parameterDataType, parameterName, …). So the getActorDetail method reads query getActorDetail(numeric actorID). You can also use the tree controls (+ andicons) next to each node of the component tree to expand and collapse the listing.

If you select the getActorDetail method and right-click, several options are presented. The middle two, Get details and Get description, are further examples of our CFC's introspective abilities. Figure 19.2 shows the Details display. It is a no-frills listing of all the method's propertiesname, package, return type, and so on.

Figure 19.2. Component details in Dreamweaver.

More important information is available in the self-documenting view into ColdFusion components; this is the HTML version of a component's documentation. There are two ways to access this document: by clicking on the Get Description option of Dreamweaver, as mentioned above, or by accessing the component directly from a browser. In the latter, direct URL method, you simply enter the URL to the CFC in a browserso in the case of the Actors component, you'd enter:

http://localhost:8500/cfadv/19/Actors.cfc

where the physical file on this machine is located off of the Web root at wwwroot\cfadv\19\actors.cfc.

When you select either of these ways of accessing the HTML version of the CFC, ColdFusion passes a request to a special template called the CFC Explorer, which is located in the ColdFusion component utilities directory ([Webroot]\CFIDE\componentutils). If ColdFusion has an RDS password specified, a prompt will require that it be entered. This prevents the components from being browsed by unauthorized outside parties. Once authorized, you will see the component's description (Figure 19.3).

Figure 19.3. Detailed component introspection page.

The benefit of using this view of a CFC (rather than that offered in the component browser in Dreamweaver) is its presentation of metadata. Each displayname and hint that was added to the component's code is presented here along with all the other details (methods, parameters, return types, etc). The result is a highly useful, human-readable reference document that is available to every member of a development team. (One need only think about ColdFusion custom tags to see the benefit of this feature. Have you have ever opened up the source code of a custom tag hoping that usage information would be provided in a header comment, and then had to try and figure it out on your own?)

Another benefit is that the introspection detail is created in real time, so this documentation is always up-to-dateif a function is added, it will be visible immediately. Of course, this also extends to the Dreamweaver component browser view, as well.

In the same directory as the component browser is a page that allows you to browse all the components on the server. Open http://localhost:8500/CFIDE/componentutils/componentdoc.cfm for a three-window frame view of the components available. This is similar to the component browser in Dreamweaver, except that the full, HTML version of the component's information is presented when the CFC is selected.

Another way of examining what a component contains is with <cfdump>. Simply create a component object with <cfcomponent>, and dump the CFC. Here's an example:

 <cfobject name="cfcActors" component="Actors"> <cfdump var="#cfcActors#" label="Actors CFC"> 

This view doesn't give you the code hints, but it does show all the methods defined in a component. Results of the foregoing example are shown in Figure 19.4.

Figure 19.4. <cfdump> of a component.

The GetMetaData() Function

That data we saw in <cfdump> can sometimes be useful to your code. ColdFusion provides a way for components to get this data and examine themselves, using a form of self-introspection. This is the getMetaData() function, which returns a structure containing the same information you can see in the HTML view of a component.

There are two syntaxes for using the getMetaData() function. From outside of a component, pass the function a reference to the component object. Within a component, pass the function the component's own scope keyword THIS. So, for example, this code:

 <cfobject component="Actors" name="cfcActors"> <cfdump var="#getMetaData(cfcActors)#"> 

will produce a structure similar to that shown in Figure 19.5.

Figure 19.5. <cfdump> of a component metadata.

With this data, you could produce component HTML documentation in whatever form you wish, simply by accessing the information in the structure. This is demonstrated in Listing 19.3, and the results are shown in Figure 19.6.

Listing 19.3. getMetaData.cfmDisplay Data Using getMetaData()

 <!---   getMetaData.cfm   Demonstrate use of getMetaData() function ---> <!--- instantiate the Actors object into cfcActors ---> <cfobject component="Actors" name="cfcActors"> <!--- now get the metadata, into the ourMetaData function ---> <cfset ourMetaData = getMetaData(cfcActors)> <cfoutput> <!--- Show the displayName and size; we could also show the hint,   path, etc. ---> <h3>Welcome to the #ourMetaData.displayName#!</h3> Enjoy our #arrayLen(ourMetaData.functions)# functions: <ul> <!--- loop through and show each function's name; could also show    hint, parameters array, etc. but let's keep it simple. ---> <cfloop index="thisFunction" from="1" to="#arrayLen(ourMetaData.functions)#"> <li>#ourMetaData.functions[thisFunction].displayName#</li> </cfloop> </ul> </cfoutput> 

Figure 19.6. User dump of component.