![]() ![]() ![]() |
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.
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.
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:
<!--- 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.
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.
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:
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.
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.
![]() ![]() ![]() |
AllaireDoc@allaire.com
Copyright © 1998, Allaire Corporation. All rights reserved.