cftree

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 trees in the Developing ColdFusion Applications

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 cfformpreserveData attribute is set to "yes"

• The cfformaction 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 cftreename 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>