Building tree controls with the cftree tag



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 the cftree tag, you use individual cftreeitem tags to populate the control.

You can create trees in three formats:

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

Flash
Generates a Flash control that you can include in an HTML or Flash form. For more information on Flash Forms see Creating Forms in Flash.

Object
Creates a hierarchical ColdFusion structure that represents the tree data and many of the cftree and cftreeitem attributes.

The different formats support different sets of features and attributes. The information here discusses general techniques that apply to all three formats, and indicates any techniques that do not apply to a specific format. It uses applet format for all examples, which use applet-specific attributes. For details on the features and attributes supported in each format, see the cftree entry in the CFML Reference.

Create and populate a tree control from a query

  1. Create a ColdFusion page with the following content:

    <cfquery name="engquery" datasource="cfdocexamples"> 
    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.

Reviewing the code

The following table describes the highlighted code and its function:

Code

Description

<cftree name="tree1"

Creates a tree and names 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 puts 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 folder and document images that ship with ColdFusion in the tree structure.

When populating a cftree tag with data from a cfquery tag, 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, to organize your employees by department, separate column names with commas in the cftreeitemvalue attribute.

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="cfdocexamples"> 
    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="computer,folder,document" 
    imgopen="computer,folder" 
    expand="yes"> 
 
</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

Orders the query results by department.

<cftreeitem value="Dept_ID,FullName"

Populates the tree with the department ID, and under each department, the full name for each employee in the department.

queryasroot="Dept_ID"

Labels the root "Dept_ID".

img="computer,folder,document"

imgopen="computer,folder"

Uses the ColdFusion supplied computer image for the root level, folder image for the department IDs, and document for the names, independent of whether any level is expanded (open) or collapsed. The imgopen attribute has only two items, because the employee names can never be open.

The cftreeitem comma-separated value, img, and imgopen attributes correspond to the tree level structure. In applet format, if you omit the img attribute, ColdFusion uses the folder image for all levels in the tree; if you omit the imgopen attribute, ColdFusion uses the folder image for all expanded levels in the tree. Flash format ignores the img and imgopen attributes and always uses folders for levels with children and documents for nodes without children.

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 cfformaction 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 the cftree tag to Yes; otherwise, the path value starts with the first node. If you specify a root name for a tree item using the queryasroot tag, 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 = 3\John Allen 
Form.tree1.node = John Allen

The deptquery root does not appear in the path, because the cftree tag does not specify completePath="Yes". You can specify the character used to delimit each element of the path form variable in the cftreedelimiter attribute. The default is a backslash character (\).

Input validation

Although the cftree tag 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 the cftree tag can be complex. Knowing how to specify the relationship between multiple cftreeitem entries helps you handle the most complex cftree constructs.

Creating a one-level tree control

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

<cfquery name="deptquery" datasource="cfdocexamples"> 
    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"> 
        img="folder,document"> 
    </cftree> 
<br> 
<cfinput type="submit" value="Submit"> 
</cfform>

Creating a multilevel tree control

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

In this example, every cftreeitem tag, except the top level Divisions, specifies a parent. For example, the cftreeitem tag specifies Divisions as its parent.

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" img="document"> 
    <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" img="document"> 
    <cftreeitem value="QA"  
        parent="Divisions" img="folder"> 
    <cftreeitem value="Product One" 
        parent="QA" img="document"> 
    <cftreeitem value="Product Two"  
        parent="QA" img="document"> 
    <cftreeitem value="Product Three" 
        parent="QA" img="document"> 
    <cftreeitem value="Support" 
        parent="Divisions" img="fixed"> 
    <cftreeitem value="Product Two" 
        parent="Support" img="document"> 
    <cftreeitem value="Sales" 
        parent="Divisions" img="computer"> 
    <cftreeitem value="Marketing" 
        parent="Divisions" img="remote"> 
    <cftreeitem value="Finance" 
        parent="Divisions" img="element"> 
</cftree> 
</cfform>

Image names in a cftree tag

Note: The information here applies to applet format trees. In Flash, you cannot control the tree icons. Flash uses open and closed folders and documents as the icons. In object format, the image information is preserved in fields in the object structure.

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

When you use the img attribute, ColdFusion displays the specified image beside the tree items when they are not open. When you use the imgopen attribute, ColdFusion displays the specified image beside the tree items when they are open (expanded). 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. You cannot use a custom image in Flash format. As a general rule, make the height of your custom images less than 20 pixels.

When populating a cftree control with data from a cfquery tag, you can use the img attribute of cftreeitem tag 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:

  • computer

  • document

  • element

  • folder

  • floppy

  • fixed

  • remote

Note: In applet format, you can also control the tree appearance by using the cftree tag lookAndFeel attribute to specify a Windows, Motif, or Metal look.

Embedding URLs in a cftree tag

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

Embed links in a cftree control

  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="Adobe Home" 
        parent="Important Links" 
        img="document" 
        href="http://www.adobe.com"> 
    <cftreeitem value="ColdFusion Developer Center" 
        parent="Important Links" 
        img="document" 
        href="http://www.adobe.com/devnet/coldfusion/"> 
</cftree> 
</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

href="http://www.adobe.com">

Makes the node of the tree a link.

href="http://www.adobe.com/devnet/mx/coldfusion/">

Makes the node of the tree a link.

Although this example does not show it, the href attribute 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 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_item_value_attribute

If the value attribute includes spaces, ColdFusion replaces the spaces with plus characters (+).

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.