Building Tree Controls with CFTREE  
 
 

The CFTREE form control is one of the most useful of the Java applet-based tags in ColdFusion. With it, you can create collapsible tree controls populated from data source queries. To build a tree control with CFTREE, you use individual CFTREEITEM tags to populate the control. Tree controls are very useful for displaying hierarchical information in a space-saving control. You can create shallow or deep tree structures, and you can specify one of six built-in icons to represent individual items in the tree control.

 
 
  Populating a tree with query data  
 
 

The following very simple CFTREE example is populated with data from a CFQUERY. It uses a minimum of CFTREE and CFTREEITEM attributes to show how you can create and populate a tree control with just a handful of CFML.

First, the query selects data from the data source:

<CFQUERY NAME="Engineering" DATASOURCE="cfsnippets">
    SELECT FirstName + ' ' + LastName AS FullName
    FROM EMPLOYEES
</CFQUERY>

Next, the CFTREE is built using data from the query:

<CFFORM NAME="form1" ACTION="submit.cfm" 
    METHOD="Post">
<CFTREE NAME="tree1" REQUIRED="yes" 
    HSCROLL="no" vSCROLL="yes">
    <CFTREEITEM VALUE=FullName
        QUERY="Engineering"
        QUERYASROOT="yes"
        IMG="folder,document">
</CFTREE>
</CFFORM>

The resulting tree control looks like this:

This example uses the QUERYASROOT attribute to specify the query name as the root level of the tree control. The QUERYASROOT attribute takes either a yes/no argument, or a name you want to appear as the root level for data returned by a CFQUERY. You could, for example, populate a CFTREE with data from several different, identical queries or from several different data sources. Using QUERYASROOT allows you to specify each individual query as the source of data for a particular section of the CFTREE.

 
 
  Grouping output from a query  
 
 

In a similar query, you may want to organize your employees by the department they work in and then display a complete list that reflects organization by department. In this case, ColdFusion provides a very simple means for displaying output from an ordered CFQUERY in a CFTREE. You separate column names with commas in the CFTREEITEM VALUE attribute, and ColdFusion understands you want the tree control to reflect the ordering of the SQL statement:

 
 
  Example: Grouping query output  
 
<!--- CFQUERY with an ORDER BY clause --->
<CFQUERY NAME="myquery" DATASOURCE="cfsnippets">
    SELECT DEPARTMENT, FirstName + ' ' + LastName 
    AS FullName
    FROM EMPLOYEES
    ORDER BY DEPARTMENT
</CFQUERY>

<!--- Build the tree control --->
<CFFORM NAME="form1" ACTION="submit.cfm" 
    METHOD="Post">

<CFTREE NAME="tree1"
    HSCROLL="no"
    VSCROLL="no"
    BORDER="yes"
    HEIGHT="350"
    REQUIRED="yes">

<CFTREEITEM VALUE="Department, FullName"
    QUERY="myquery"
    QUERYASROOT="Department"
    IMG="cd,folder">

</CFTREE>

<BR><INPUT TYPE="Submit" VALUE="Submit">
</CFFORM>

Note how comma-separated items in the IMG and the VALUE attributes correspond. The first column, Department, is represented with one of ColdFusion's built-in CFTREE images, the CD image. The second column, FullName, is represented with another built-in image, the folder. If the IMG attribute is left out altogether, ColdFusion uses the folder image for all levels in the tree.

The resulting tree control looks like this:

If the user selects the name "Peter Jacobsen" in this tree, the following form variables are returned by ColdFusion:

form.tree1.node = Peter Jacobsen
form.tree1.path = Department\Sales\Peter Jacobsen

You can specify the backslash character used to delimit each element of the path form variable in the CFTREE DELIMITER attribute.

 
 
  Note  
 

The following tree examples all use the result set from the CFQUERY above. The datasource, a Microsoft Access database called cfsnippets.mdb, is installed with CFAS. To run any of the tree examples, just reference "myquery" or drop the query into your test template.

 
 
  CFTREE form variables  
 
 

The CFTREE tag allows you to force a user to select an item from the tree control by setting the REQUIRED attribute to YES. With or without the REQUIRED attribute, ColdFusion passes two form variables to the application page specified in the CFTREE ACTION attribute:

  • form.treename.node -- Returns the node of the user selection.
  • form.treename.path -- Returns the complete path of the user selection, in the form: root\node1\node2\node_n\value

The root part of the path is only returned if you set the COMPLETEPATH attribute of CFTREE to YES; otherwise, the path value starts with the first node.

 
 
  Input validation with CFTREE  
 
 

With CFTREE controls, there is no VALIDATE attribute with which, using other CFFORM controls, you can validate a number of data types. However, you can use the REQUIRED attribute in CFTREE to force a user to select an item from the tree control. In addition, you can specify a JavaScript in the ONVALIDATE attribute to perform validation.



 
 
BackUp LevelNext
 
 

allaire     AllaireDoc@allaire.com
    Copyright © 1998, Allaire Corporation. All rights reserved.