Building Tree Controls with cftree

The cftree form lets you display hierarchical information 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 URL to your own gif image.

To create and populate a tree control from a query:

Open a new file named tree1.cfm in ColdFusion Studio.

Modify the page so that it appears as follows:

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

Save the page and view it in your browser.

Reviewing the code

The following table describes the highlight code and its function:

Code

Description

<cftree name="tree1"
Create a tree and name it tree1.

required="Yes"
Specify that a user must select an item in the tree.

hscroll="No"
Don't allow horizontal scrolling.

<cftreeitem value=FullName query="engquery"
Create 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"
Specify the query name as the root level of the tree control.

img="folder,document"
Use the images "folder" and "document" that ship with ColdFusion in the tree structure.

Code	Description
<cftree name="tree1"	Create a tree and name it tree1.
required="Yes"	Specify that a user must select an item in the tree.
hscroll="No"	Don't allow horizontal scrolling.
<cftreeitem value=FullName query="engquery"	Create 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"	Specify the query name as the root level of the tree control.
img="folder,document"	Use the images "folder" and "document" that ship with ColdFusion in the tree structure.

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:

Open a new file named tree2.cfm in ColdFusion Studio.

Modify the page so that it appears as follows:

<!--- 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"
  method="Post">

<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>

Save the page and view it in your browser.

Reviewing the code

The following table describes the highlight 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.

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.

Note that 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.

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

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 in queryastroot, that value gets returned as the root.

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

Form.tree1.node = John Allen
Form.tree1.path = Dept_ID\3\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.

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 the JavaScript code to perform validation.

Return to Firstserv.com | ColdFusion Hosting | Macromedia LiveDocs

Developing ColdFusion Applications
Building Dynamic Forms