Section 10.3. CFX Custom Tags

10.3 CFX Custom Tags

Another popular way to gain the power of the Java language while working within the ease of the ColdFusion environment is to write CFX custom tags.

To write a CFX custom tag, you write the Java code that will create the object you want to use. Then you register the code with the ColdFusion Administrator so that ColdFusion knows what code base to run when you invoke the tag.

Before writing your own custom tags, it is not a bad idea to look at the CFX tags that Macromedia ships with the CFMX server. You can find these source files in <CFMX_HOME>\cfx\java\distrib\examples . This directory contains several examples, ranging from a simple "Hello, World" tag, to one that creates custom graphics for you.

It is a little extra work to turn regular Java classes into CFX tags. The first thing you need to do is write a Java file that imports the Allaire interfaces for using CFX tags, and then implement the CustomTag interface in your class definition. This archive in ColdFusion 5 and prior is located at <CF_HOME>\java\classes\cfx.jar . In CFMX, this .jar file is located in <CFMX_HOME>\lib\cfx.jar . In the ColdFusion Administrator, add this .jar to your class path as shown in the previous section. Once you have added it to your class path , use the JRun launcher to restart the server.

The cfx.jar file makes three interfaces available to you:

Request represents a request made of a CFX tag, including parameters passed to it as attributes.
Response represents a response that the CFX tag creates to return to the client.
Query represents a query that the CFX uses. With this object you can extend the functionality that the <cfquery> tag makes available.

We will look at what these interfaces expose in a bit. For now, let's write the simplest possible CFX tag to make sure that everything is working.

10.3.1 `SimpleMessage.java`

 /* custom CFX tag. prints a message */  import com.allaire.cfx.*; import java.util.*; import java.text.DateFormat; public class SimpleMessage implements CustomTag { Date now = new Date(); DateFormat f = DateFormat.getDateInstance(DateFormat.FULL, Locale.US);    public void processRequest(Request request, Response response)       throws Exception    {       f.format(now);       String name = request.getAttribute( "NAME" ) ;       response.write( "Hello, " + name + "!  " +    "Today is " + f) ;    } }

10.3.2 `CallCFX.cfm`

 <html>  <head> <title>CFX example</title> </head> <body> <!---call the CFX_SimpleMessage tag---> <CFX_SimpleMessage NAME="DoodleHead"> <cfoutput>#msg#</cfoutput> </body>  </html>

If you cannot compile the source file, it is almost certainly because the compiler cannot find the .jar file to import the Allaire interfaces. You can compile from the command line, specifying the path to the cfx.jar and the full path to your SimpleMessage.java file, like this:

 >javac -classpath %CLASSPATH%;c:CFusionMX\lib\cfx.jar     C:\CFusionMX\wwwroot\chp10\SimpleMessage.java

Once you have compiled the Java source, you can call this tag directly as shown using CallCFX.cfm . The registration process in the ColdFusion Administrator is not required if your tag is in the same directory as the calling page. Otherwise, you can put it under the CustomTags subdirectory of CFusionMX_HOME .

Note

If you have loaded a CFX tag and then modified its source and recompiled it, you may notice that ColdFusion does not read the new tag. This is because it caches CFX tags when the server is first started. Try deleting the class file, shutting down the ColdFusion Application service, and then recompiling. Restart the application server, and it should read your modified class.

You'll notice in the custom tag a few Java items that are specific to using CFX tags. First, we have to import the package com.allaire.cfx, which has the interfaces we must implement in order to use the CFX functionality in our pages. Second, our Java class must implement the CustomTag interface. This implementation must account for HTTP request and response in a manner similar to servlets. We named the method that does the work processRequest . This is not arbitrary, and you must name the main method in a CFX Java file processRequest , and it must accept request and response as parameters. The remainder of the definition is straightforward Java.

10.3.3 The Java CFX Objects

Here let us examine the three Java objects available for use within CFX tags.

There are three objects made available to CFX developers: Request , Response , and Query , which are outlined in Tables 10.2 through 10.4.

The Request object aids in retrieving information sent from the HTTP request, including attributes and query information. The Response object allows you to send information back in the response generated; typically it is used to write text to the output stream. The Query object defines methods that allow you to manipulate database queries passed into the tag from the calling template.

Table 10.2. The CFX `Request` Object

Method	Description
`attributeExists`	Determines whether the attribute specified was passed into the tag
`debug`	Determines whether the tag contains the `DEBUG` attribute
`getAttribute`	Gets the value of the passed attribute
`getAttributeList`	Gets all attributes passed into the tag
`getIntAttribute`	Gets the value of the passed attribute as an `int`
`getQuery`	Gets a query passed into the tag
`getSetting`	Gets the value of a setting global to custom tags

Table 10.3. The CFX `Response` Object

Method	Description
`addQuery`	Adds a query to the calling template
`setVariable`	Sets a variable in the calling template
`write`	Outputs text to the calling page
`writeDebug`	Outputs text to the debug output stream

You can use CFX tags to improve on or extend existing CF tags, and in fact one of the sample files included with CFMX does that with <cfquery> . CFX tags used to have the benefit of processing more quickly than complex logic written in regular ColdFusion, because they were compiled. Now that all ColdFusion code is compiled and Macromedia has introduced CFCs (ColdFusion Components), there is less reason to use CFX tags. ColdFusion Components are essentially an easy front-end wrapper for writing Java classes; CFXs let you write straight Java. You may find that in certain cases you have Java code that you would like to use from within ColdFusion and that it is easier to deploy a CFX than to rewrite it as a component. The advantage of working with CFXs as opposed to calling <cfobject> is that you needn't riddle your ColdFusion template with a good deal of code that interacts with the object; a CFX tag makes a neater, cleaner, and more compact interface. A primary objective of working with Java code on the Web is to keep a clear separation of the worker classes in the logic layer and the presentation layer. We will find out more about this when we write servlets and JSP. CFXs encourage this separation.

Table 10.4. The CFX `Query` Object

Method	Description
`addRows`	Adds a new row to the `Query` object
`getColumns`	Gets the names of the columns in the query
`getData`	Gets an element of data from the query
`getName`	Gets the name of the query
`getRowCount`	Gets the number of rows returned by the query
`setData`	Sets an element of data within the query

Top

10.3 CFX Custom Tags

10.3.1 SimpleMessage.java

10.3.2 CallCFX.cfm

10.3.3 The Java CFX Objects

Table 10.2. The CFX Request Object

Table 10.3. The CFX Response Object

Table 10.4. The CFX Query Object

10.3.1 `SimpleMessage.java`

10.3.2 `CallCFX.cfm`

Table 10.2. The CFX `Request` Object

Table 10.3. The CFX `Response` Object

Table 10.4. The CFX `Query` Object