# CFTREE

The CFTREE form custom control allows you to place a tree control in a CFFORM. User selections can be validated. Individual tree items are created with CFTREEITEM tags inside the CFTREE tag block.

Note | CFTREE incorporates a Java applet, so a browser must be Java-enabled for CFTREE to work properly.

### Syntax

    <CFTREE NAME="name"
        REQUIRED="Yes/No"
        DELIMITER="delimiter"
        COMPLETEPATH="Yes/No"
        APPENDKEY="Yes/No"
        HIGHLIGHTHREF="Yes/No"
        ONVALIDATE="script_name"
        MESSAGE="text"
        ONERROR="text"
        FONT="font"
        FONTSIZE="size"
        ITALIC="Yes/No"
        BOLD="Yes/No"
        HEIGHT="integer"
        WIDTH="integer"
        VSPACE="integer"
        HSPACE="integer"
        ALIGN="alignment"
        BORDER="Yes/No"
        HSCROLL="Yes/No"
        VSCROLL="Yes/No"
        NOTSUPPORTED="text">

    </CFTREE>

#### NAME

Required. A name for the CFTREE control.

#### REQUIRED

Optional. Yes or No. User must select an item in the tree control. Default is No.

#### DELIMITER

Optional. The character used to separate elements in the form variable PATH. The default is "\".

#### COMPLETEPATH

Optional. Yes passes the root level of the treename.path form variable when the CFTREE is submitted. If omitted or No, the root level of this form variable is not included.

#### APPENDKEY

Optional. Yes or No. When used with HREF, Yes passes the CFTREEITEMKEY variable along with the value of the selected tree item in the URL to the application page specified in the CFFORM ACTION attribute. The default is Yes.

#### HIGHLIGHTHREF

Optional. Yes highlights links associated with a CFTREEITEM with a URL attribute value. No disables highlight. Default is Yes.

#### ONVALIDATE

Optional. The name of a valid JavaScript function used to validate user input. The form object, input object, and input object value are passed to the specified routine, which should return true if validation succeeds and false otherwise.

#### MESSAGE

Optional. Message text to appear if validation fails.

#### ONERROR

Optional. The name of a valid JavaScript function you want to execute in the event of a failed validation.

#### FONT

Optional. Font name to use for all data in the tree control.

#### FONTSIZE

Optional. Font size for text in the tree control, measured in points.

#### ITALIC

Optional. Yes or No. Yes presents all tree control text in italic. Default is No.

#### BOLD

Optional. Yes or No. Yes presents all tree control text in boldface. Default is No.

#### HEIGHT

Optional. Height value of the tree control, in pixels.

#### WIDTH

Optional. Width value of the tree control, in pixels.

#### VSPACE

Optional. Vertical margin spacing above and below the tree control in pixels.

#### HSPACE

Optional. Horizontal spacing to the left and right of the tree control, in pixels.

#### ALIGN

Optional. Alignment value. Valid entries are:

- Top
- Left
- Bottom
- Baseline
- TextTop
- AbsBottom
- Middle
- AbsMiddle
- Right

#### BORDER

Optional. Places a border around the tree. Default is Yes.

#### HSCROLL

Optional. Permits horizontal scrolling. Default is Yes.

#### VSCROLL

Optional. Permits vertical scrolling. Default is Yes.

#### NOTSUPPORTED

Optional. The text you want to display if the page containing a Java applet-based CFFORM control is opened by a browser that does not support Java or has Java support disabled. For example:

    NOTSUPPORTED="<B> Browser must support Java to
    view ColdFusion Java Applets</B>"

By default, if no message is specified, the following message appears:

    <B>Browser must support Java to <BR>
    view ColdFusion Java Applets!</B>

### Example

    <!--- This example shows the use of CFTREE in a CFFORM.
    The query takes a list of employees, and uses CFTREE and CFSELECT
    to display the results of the query.  In addition, CFGRID is used
    to show an alternate means of displaying the same data --->
    <!--- set a default for the employeeNames variable --->
    <CFPARAM NAME="employeeNames" DEFAULT="">
    <!--- if an employee name has been passed from the form,
    set employeeNames variable to this value --->
    <CFIF IsDefined("form.employeeNames")>
        <CFSET employeeNames = form.employeeNames>
    </CFIF>
    <!--- query the datasource to find the employee information--->
    <CFQUERY NAME="GetEmployees" DATASOURCE="cfsnippets">
    SELECT   Emp_ID, FirstName, LastName, EMail, Phone, Department
    FROM     Employees where lastname
             <CFIF #employeeNames# is not "">= '#employeeNames#'</CFIF>
    </CFQUERY>
    <HTML>
    <HEAD>
    <TITLE>
    CFTREE Example
    </TITLE>
    </HEAD>

    <BODY>
    <H3>CFTREE Example</H3>

    <!--- Use CFFORM when using other CFINPUT tools --->
    <CFFORM ACTION="cftree.cfm" METHOD="POST" ENABLECAB="Yes">
    <!--- Use CFSELECT to present the contents of the query by column --->
    <H3>CFSELECT Presentation of Data</H3>
    <H4>Click on an employee's last name and hit "see information for
    this employee" to see expanded information.</H4>

    <CFSELECT NAME="EmployeeNames" MESSAGE="Select an Employee Name"
        SIZE="#getEmployees.recordcount#" QUERY="GetEmployees"
        VALUE="LastName" REQUIRED="No">
        <OPTION value="">Select All
    </CFSELECT>

    <INPUT TYPE="Submit" NAME="" VALUE="see information for this employee">

    <!--- showing the use of CFTREE --->
    <!--- Use CFTREE for an expanded presentation of the data --->
    <!--- Loop through the query to create each branch of the CFTREE --->
    <H3>CFTREE Presentation of Data</H3>
    <H4>Click on the folders to "drill down" and reveal information.</H4>
    <P>CFTREEITEM is used to create the "branches" of the tree.
    <P>
    <CFTREE NAME="SeeEmployees" HEIGHT="150" WIDTH="240"
        FONT="Arial Narrow" BOLD="No"
        ITALIC="No" BORDER="Yes"
        HSCROLL="Yes" VSCROLL="Yes"
        REQUIRED="No" COMPLETEPATH="No"
        APPENDKEY="Yes" HIGHLIGHTHREF="Yes">
    <CFLOOP QUERY="GetEmployees">
        <CFTREEITEM VALUE="#Emp_ID#" PARENT="SeeEmployees" EXPAND="No">
        <CFTREEITEM VALUE="#LastName#" DISPLAY="Name"
            PARENT="#Emp_ID#" QUERYASROOT="No"
            EXPAND="No">
        <CFTREEITEM VALUE="#LastName#, #FirstName#"
            PARENT="#LastName#" EXPAND="No"
            QUERYASROOT="No">
        <CFTREEITEM VALUE="#Department#" DISPLAY="Department"
            PARENT="#Emp_ID#" QUERYASROOT="No"
            EXPAND="No">
        <CFTREEITEM VALUE="#Department#" PARENT="#Department#"
            EXPAND="No" QUERYASROOT="No">
        <CFTREEITEM VALUE="#Phone#" DISPLAY="Phone"
            PARENT="#Emp_ID#" QUERYASROOT="No"
            EXPAND="No">
        <CFTREEITEM VALUE="#Phone#" PARENT="#Phone#"
            EXPAND="No" QUERYASROOT="No">
        <CFTREEITEM VALUE="#Email#" DISPLAY="Email" PARENT="#Emp_ID#"
              QUERYASROOT="No" EXPAND="No">
        <CFTREEITEM VALUE="#Email#" PARENT="#Email#" EXPAND="No"
            QUERYASROOT="No">
    </CFLOOP>
    </CFTREE>
    ...