Developing ColdFusion MX Applications with CFML
Building Dynamic Forms

Building tree controls with cftree

The cftree tag lets you display hierarchical information within a form in a space-saving collapsible tree populated from data source queries. To build a tree control with cftree, you use individual cftreeitem tags to populate the control. You can specify one of six built-in icons to represent individual items in the tree control, or supply a file path or URL to your GIF image.

Note:   The cftree tag requires the client to download a Java applet. Downloading an applet takes time; therefore, using cftree can be slightly slower than using an HTML form element to retrieve the same information. In addition, browsers must be Java-enabled for cftree to work properly.

To create and populate a tree control from a query:

1. Create a ColdFusion page with the following content:

   <cfquery name="engquery" datasource="CompanyInfo">
     SELECT FirstName + ' ' + LastName AS FullName
     FROM Employee
   </cfquery>
   <cfform name="form1" action="submit.cfm">
   <cftree name="tree1" 
     required="Yes" 
     hscroll="No">
     <cftreeitem value="FullName"
       query="engquery"
       queryasroot="Yes"
       img="folder,document">
   </cftree>
   </cfform>
   

2. Save the page as tree1.cfm and view it in your browser.

   The following figure shows the output of this code:

   

Reviewing the code

The following table describes the highlighted code and its function:

Code	Description
<cftree name="tree1"	Creates a tree and name it tree1.
required="Yes"	Specifies that a user must select an item in the tree.
hscroll="No"	Does not allow horizontal scrolling.
<cftreeitem value="FullName" query="engquery"	Creates an item in the tree and put the results of the query named engquery in it. Because this tag uses a query, it puts one item on the tree per query entry.
queryasroot="Yes"	Specifies the query name as the root level of the tree control.
img="folder,document"	Uses the images "folder" and "document" that ship with ColdFusion in the tree structure. When populating a cftree with data from a cfquery, you can specify images or filenames for each level of the tree as a comma-separated list.

Grouping output from a query

In a query that you display using a cftree control, you might want to organize your employees by the department. In this case, you separate column names with commas in the cftreeitem value attribute.

To organize the tree based on ordered results of a query:

1. Create a ColdFusion page named tree2.cfm with the following content:

   <!--- CFQUERY with an ORDER BY clause --->
   <cfquery name="deptquery" datasource="CompanyInfo">
     SELECT Dept_ID, FirstName + ' ' + LastName
     AS FullName
     FROM Employee
     ORDER BY Dept_ID
   </cfquery>
   
   <!--- Build the tree control --->
   <cfform name="form1" action="submit.cfm">
   
   <cftree name="tree1"
     hscroll="No"
     border="Yes"
     height="350"
     required="Yes">
   
   <cftreeitem value="Dept_ID, FullName"
     query="deptquery"
     queryasroot="Dept_ID"
     img="cd,folder">
   
   </cftree>
   <br>
   <br><input type="Submit" value="Submit">
   </cfform>
   

2. Save the page and view it in your browser.

   

Reviewing the code

The following table describes the highlighted code and its function:

Code	Description
ORDER BY Dept_ID	Order the query results by department.
<cftreeitem value="Dept_ID,FullName"	Populate the tree with the Department ID, and under each department, the Full Name for each employee in the department.
queryasroot="Dept_ID"	Label the root "Dept_ID".
img="cd,folder">	Use the ColdFusion-supplied CD image for the root level and Folder image for the department IDs. The names are preceded by a bullet.

The cftreeitem comma-separated img and the value attributes both correspond to the tree level structure. If you leave out the img attribute, ColdFusion uses the folder image for all levels in the tree except the individual items, which have bullets.

The cftree form variables

The cftree tag lets you 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 cfform action attribute:

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

To return the root part of the path, set the completepath attribute of cftree to Yes; otherwise, the path value starts with the first node. If you specify a root name for a tree item using queryasroot, that value is returned as the root. If you do not specify a root name, ColdFusion returns the query name as the root. If there is no query name, ColdFusion returns the tree name as the root.

In the previous example, if the user selects the name "John Allen" in the tree, ColdFusion returns the following form variables:

Form.tree1.path = Dept_ID\3\John Allen

Form.tree1.node = John Allen

You can specify the character used to delimit each element of the path form variable in the cftree delimiter attribute. The default is a backslash character.

Input validation

Although the cftree does not include a validate attribute, you can use the required attribute to force a user to select an item from the tree control. In addition, you can use the onvalidate attribute to specify your own JavaScript code to perform validation.

Structuring tree controls

Tree controls built with cftree can be very complex. Knowing how to specify the relationship between multiple cftreeitem entries helps you handle the most complex of cftree constructs.

Creating a one-level tree control

The following example consists of a single root and a number of individual items:

<cfquery name="deptquery" datasource="CompanyInfo">
  SELECT Dept_ID, FirstName + ' ' + LastName
  AS FullName
  FROM Employee
  ORDER BY Dept_ID
</cfquery>

<cfform name="form1" action="submit.cfm">
  <cftree name="tree1">
    <cftreeitem value="FullName"
    query="deptquery"
    queryasroot="Department">
  </cftree>
<br>
<input type="submit" value="Submit">
</cfform>

Creating a multilevel tree control

The following figure shows an example of a multilevel tree:

When populating a cftree, you create the multilevel structure of the tree by specifying a parent for each cftreeitem in the tree. The parent attribute of cftreeitem allows your cftree to show relationships between elements in the tree.

In this example, every cftreeitem, except the top level Divisions, specifies a parent. For example, the cftreeitem Development specifies a parent of Divisions.

The following code populates the tree directly, not from a query:

<cfform name="form2" action="cfform_submit.cfm">

<cftree name="tree1" hscroll="No" vscroll="No"
  border="No">
  <cftreeitem value="Divisions">
  <cftreeitem value="Development" 
    parent="Divisions" img="folder">
  <cftreeitem value="Product One" 
    parent="Development">
  <cftreeitem value="Product Two" 
    parent="Development">
  <cftreeitem value="GUI" 
    parent="Product Two" img="document">
  <cftreeitem value="Kernel" 
    parent="Product Two" img="document">
  <cftreeitem value="Product Three" 
    parent="Development">
  <cftreeitem value="QA" 
    parent="Divisions" img="folder">
  <cftreeitem value="Product One"
    parent="QA">
  <cftreeitem value="Product Two" parent="QA">
  <cftreeitem value="Product Three"
    parent="QA">
  <cftreeitem value="Support"
    parent="Divisions" img="fixed">
  <cftreeitem value="Product Two"
    parent="Support">
  <cftreeitem value="Sales"
    parent="Divisions" img="cd">
  <cftreeitem value="Marketing"
    parent="Divisions" img="document">
  <cftreeitem value="Finance"
    parent="Divisions" img="element">
</cftree>

</cfform>

Image names in a cftree

The default image displayed in a tree is a folder. However, you can use the img attribute of cftreeitem to specify a different image.

When you use the img attribute, ColdFusion displays the specified image beside the tree items. You can specify a built-in ColdFusion image name, the file path to an image file, or the URL of an image of your choice, such as http://localhost/Myapp/Images/Level3.gif. As a general rule, make the height of your custom images less than 20 pixels.

When populating a cftree with data from a cfquery, you can use the img attribute of cftreeitem to specify images or filenames for each level of the tree as a comma-separated list.

The following are the ColdFusion built-in image names:

• cd
• computer
• document
• element
• folder
• floppy
• fixed
• remote

Note:   You can also control the tree appearance by using the lookAndFeel attribute to specify a Windows, Motif, or Metal look.

Embedding URLs in a cftree

The href attribute in the cftreeitem tag lets you designate tree items as links. To use this feature in a cftree, you define the destination of the link in the href attribute of cftreeitem. The URL for the link can be a relative URL or an absolute URL as in the following examples.

To embed links in a cftree:

1. Create a ColdFusion page named tree3.cfm with the following contents:

   <cfform action="submit.cfm">
   
   <cftree name="oak"
     highlighthref="Yes"
     height="100"
     width="200"
     hspace="100"
     vspace="6"
     hscroll="No"
     vscroll="No"
     border="No">
   
     <cftreeitem value="Important Links">
     <cftreeitem value="Macromedia Home"
       parent="Important Links"
       img="document"
       href="http://www.macromedia.com">
     <cftreeitem value="ColdFusion Home"
       parent="Important Links"
       img="document"
       href="http://www.coldfusion.com">
   </cftree>
   </cfform>
   

2. Save the page and view it in your browser. The following figure shows the output of this code:

   

Reviewing the code

The following table describes the highlighted code and its function:

Code	Description
href="http://www.macromedia.com">	Makes the node of the tree a link.
href="http://www.coldfusion.com">	Makes the node of the tree a link. Although this example does not show it, href can refer to the name of a column in a query if that query populates the tree item.

Specifying the tree item in the URL

When a user clicks on a tree item to link to a URL, the cftreeItemKey variable, which identifies the selected value, is appended to the URL in the following form:

http://myserver.com?cftreeitemkey =selected_value

Automatically passing the name of the selected tree item as part of the URL makes it easy to implement a basic "drill down" application that displays additional information based on the selection. For example, if the specified URL is another ColdFusion page, it can access the selected value as the variable URL.cftreeitemkey.

To disable this behavior, set the appendkey attribute in the cftree tag to No.

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments

Add Comment

schmidt1 said on Feb 6, 2003 at 5:48 PM :

The documentation you provided on CFTREE is excellent. The examples and code provided has made my job easier. Thanks.
If all software companies could provide easy to use examples
then software development would become a whole lot easier.

Database Developer
(CF Apprentice)

No screen name said on Oct 15, 2003 at 12:24 AM :

Superbe !
Merci !

No screen name said on Nov 8, 2003 at 9:49 AM :

Hi:

I was trying to use the cftree example in our company, but in the list i COULD NOT SEE enything, please help me to solve this mistery, is very important for me because we are developing a important system under ColdFusion platform.

Thanks

Saludos de Mexico

Gustavo Gomez Rojas
Banjercito TI Manager

jrunrandy said on Nov 10, 2003 at 12:53 PM :

The example doesn't work because of a bug in ColdFusion. To fix the bug, download the hotfix at http://www.macromedia.com/support/coldfusion/ts/documents/tn17883.htm.

forum1 said on Jun 23, 2004 at 1:59 PM :

The documentation is good. But is there a way to change to color of the text in the tree or the color of the background? After we click on the hyperlink, the color of the treeitem changes to pale blue, which makes it difficult to read. How do we change this?

Thank you.

halL said on Jun 23, 2004 at 2:37 PM :

For a detailed reference page that documents all cftree attributes, see:
http://livedocs.macromedia.com/coldfusion/6/CFML_Reference/Tags-pt316.htm for ColdFusion MX
http://livedocs.macromedia.com/coldfusion/6.1/htmldocs/tags-c16.htm for ColdFusion MX 6.1.

faweisser said on Aug 19, 2004 at 9:02 AM :

I am also running into problems with the color of the hyperlinks after being clicked on. Visited links are a nearly unreadable aqua color. How can I change this? Other than that, cftree is working reasonably well.

faweisser

ciaranfarrell said on Nov 16, 2004 at 3:30 AM :

Is there any known issue or bug with ColdFusion 6 which would cause a tree written written with CFTREE, which was working perfectly with ColdFusion 5, to give strange results?

(Information in subcategories appears as main tree node, etc)
CF

ultrarodMX said on Dec 15, 2004 at 11:11 AM :

At the first example of grouping output from a query i copied all the code as you have at http://livedocs.macromedia.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/dynamicForms3.htm

i ran it, it displayed the tree, and then i selected a name and clicked the submit button, but it just sent me a message that happened when you don't select any option.

i created a template to display de values sent, disabled the "required" option and there wasn't values to show.

Whta it's going on?

No screen name said on Feb 14, 2005 at 7:05 AM :

Please,
Send some example coding in cfm.
Thank You,
T.R.Suthahar

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/dynamicForms3.htm

Add Comment