Description

Inserts a tree control in a form. Validates user selections. Used within a cfform tag block. Use a ColdFusion query to supply data to the tree.

Category

Forms tags

Syntax

<cftree
    name="name"
    align="top|left|bottom|baseline|texttop|absbottom|
        middle|absmiddle|right"
    appendKey="yes|no"
    bold="yes|no"
    border="yes|no"
    cache="yes|no"
    completePath="yes|no"
    delimiter="delimiter"
    enabled="yes|no"
    font="font"
    fontSize="size"
    format="applet|flash|html|object|xml"
    height="integer"
    highlightHref="yes|no"
    hScroll="yes|no"
    hSpace="integer"
    italic="yes|no"
    lookAndFeel="motif|windows|metal"
    message="text"
    notSupported="text">
    onBlur="ActionScript to invoke"
    onChange="ActionScript to invoke"
    onError="text"
    onFocus="Actionscript to invoke"
    onValidate="script name"
    required="yes|no"
    style= "style specification"
    tooltip="text"
    visible="yes|no"
    vScroll="yes|no"
    vSpace="integer"
    width="integer">
</cftree>

See also

cfajaximport, cfapplet, cfcalendar, cfform, cfformgroup, cfformitem, cfgrid, cfinput, cfselect, cfslider, cftextarea, cftreeitem; "Working with action pages" ,"Building tree controls with the cftree tag" ,and "Using HTML format trees" in the ColdFusion Developer's Guide

History

ColdFusion 8: Added support for Ajax based HTML trees, including the cache attribute and the html value for format attribute.

ColdFusion MX7.01: Added support for onBlur and onFocus events.

ColdFusion MX 7:

• Added the format attribute and support for generating Flash and XML and object output.
• Added enabled, onChange, style, tooltip, and visible attributes (Flash format only).

ColdFusion MX: Changed behavior: ColdFusion renders a tree control regardless of whether there are any treeitems within it.

Attributes

Usage

This tag must be in a cfform tag block.

The applet format tree requires the client to download a Java applet. Also, if the client does not have an up-to-date Java plug-in installed, the system might also have to download an updated Java plug-in to display an applet format tree. The Flash format tree uses a Flash control, and can be embedded in an HTML format cfform tag. For this tag to work properly in Flash, HTML, or applet format, the browser must also be JavaScript-enabled.

If the following conditions are true, a user's selection from query data that populates this tag's options continues to display after the user submits the form:

• The cfform preserveData attribute is set to "yes"
• The cfform action attribute posts to the same page as the form itself (this is the default), or the action page has a form that contains controls with the same names as corresponding controls on the user entry form

For more information, see the cfform tag entry.

Form variables

When you select a tree item and submit the form that contains the tree, ColdFusion creates a structure with two variables in the action page Form scope. The structure name is the tree name. The following table lists the fields:

object format

If you specify object in the format attribute, ColdFusion returns the tree as a ColdFusion structure, and does not send the tree to the browser. You can, for example, loop over the structure to populate a menu, generate "breadcrumb" links for page navigation, or create a DHTML tree.

The structure variable name is specified by the cftree name attribute. The top level of the structure has two types of entries:

• Attribute settings
• A children array

Attribute settings

The structure has top-level entries with the values of the following cftree attributes:

Children array

The top-level children entry is an array of items entries. Each item has the following entries:

Example

The following example creates a tree that shows available courses from the CourseList table of the cfdocexamples database, and puts each department's courses in a folder. This example is displayed in Flash and uses the Departments list to get department names.

<cfquery name="getCourses" datasource="cfdocexamples">
    SELECT d.dept_name, c.course_id, c.CorName, c.CorLevel, c.corName ||' ( ' ||c.corLevel ||' )' AS corLabel
    FROM CourseList c, Departments d
    WHERE d.Dept_ID = c.Dept_ID
    ORDER BY d.dept_Name, c.corName, c.corLevel
</cfquery>

<cfform name="studentForm" format="flash" width="400" height="450">
    <cftree name="courseTree" width="350" height="400">
        <cftreeitem 
            query="getCourses" 
            value="dept_name,Course_id" 
            display="dept_name,CorLabel" queryasroot="NO" expand="yes,no">
    </cftree>
</cfform>

The following example creates a tree that shows the basic information about all employees in an organization, organized by department. The departments are expanded to show all employees. You click the + signs to display additional information. If you click the employee name, ColdFusion links back to the same page and displays the Path and node values for the selection.

<!--- Query the datasource to get employee information. --->
<!--- Group the output by Department. 
    (All fields are required in Group By clause.) --->
<cfquery name = "GetEmployees" dataSource = "cfdocexamples">
    SELECT Emp_ID, FirstName, LastName, EMail, Phone, Department
    FROM Employees 
    GROUP BY Department, Emp_ID, FirstName, LastName, EMail, Phone
</cfquery>
<html>
<body>
<h3>cftree Example</h3>

<!--- The following runs if the user clicked on a link in the tree. 
    A complete application would use the ID for additional processing. --->

<cfif isdefined("Form.fieldnames")>
<b>Selected item information</b><br>
<cfoutput>
<b>Path: </b>#form.Employees.Path#<br>
<b>node: </b>#form.Employees.node#<br>
<br>
</cfoutput>
</cfif>

<!--- Display the tree. The cftree tag must be in a cfform. --->
<cfform action="#cgi.script_name#" preservedata="Yes" format="Flash">
    <cftree name = "Employees" height = "400" width = "400" 
        font = "Arial Narrow" italic="yes" highlighthref="No" HScroll="no" VScroll="no"
        completepath="no" lookandfeel="windows" border="No" required="yes"> 
        <!--- cfoutput tag with a group attribute loops over the departments. --->
        <cfoutput group="Department" query = "GetEmployees">
            <cftreeitem value="#Department#" parent="Employees" expand="yes">
            <!--- This cfoutput tag loops over the records for the department.
                    The cfoutput tag does not need any attributes. --->
            <cfoutput>
                <!--- Create an item for each employee in the department.
                    Do not expand children. Each employee name links to this page,
                    and sends the employee ID in the query string.--->
                <cftreeitem value = "#LastName#, #FirstName#"
                    parent = "#Department#" expand="false" img="cd"
                    href="#cgi.script_name#?user_id=#emp_id#">
                <!--- Each Employee entry has Id, and contact info children. --->
                <cftreeitem value = "#Emp_ID#" display = "Employee ID: #Emp_ID#" 
                    parent = "#LastName#, #FirstName#" img="remote">
                <!--- Each node must be unique value, so use Emp_ID om value. --->
                <cftreeitem value = "#Emp_ID#_ContactInfo" img="computer"
                    display = "Contact Information" 
                    parent = "#LastName#, #FirstName#" expand = "false">
                <!--- ContacInfo has two children --->
                <cftreeitem value = "#Phone#" parent = "#Emp_ID#_ContactInfo">
                <cftreeitem value = "#Email#" parent = "#Emp_ID#_ContactInfo">
            </cfoutput>
        </cfoutput>
    </cftree>
    <cfinput type="Submit" name="submitit" value="Submit" width="100">
</cfform>