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:

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>

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.

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:

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>

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.

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:

Multilevel tree control

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:

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>

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.

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.

Developing ColdFusion MX Applications with CFML
Building Dynamic Forms

Building tree controls with cftree

To create and populate a tree control from a query:

Reviewing the code

Grouping output from a query

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

Reviewing the code

The cftree form variables

Input validation

Structuring tree controls

Creating a one-level tree control

Creating a multilevel tree control

Image names in a cftree

Embedding URLs in a cftree

To embed links in a cftree:

Reviewing the code

Specifying the tree item in the URL

Comments