cftree

Description

Inserts a tree control in a form. Validates user selections. Used within a cftree tag block. You can use a ColdFusion query to supply data to the tree.

Syntax

<cftree name = "name"
  required = "Yes" or "No"
  delimiter = "delimiter"
  completePath = "Yes" or "No"
  appendKey = "Yes" or "No"
  highlightHref = "Yes" or "No"
  onValidate = "script_name"
  message = "text"
  onError = "text"
  lookAndFeel = "motif" or "windows" or "metal"
  font = "font"
  fontSize = "size"
  italic = "Yes" or "No"
  bold = "Yes" or "No"
  height = "integer"
  width = "integer"
  vSpace = "integer"
  hSpace = "integer"
  align = "alignment"
  border = "Yes" or "No"
  hScroll = "Yes" or "No"
  vScroll = "Yes" or "No"
  notSupported = "text">
 
</cftree>

History

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

Attributes

Attribute Req/Opt Default Description

name
Required

Name for tree control.

required
Optional
No

Yes: user must select an item in tree control

No

delimiter
Optional
\\
Character to separate elements in form variable path.

completePath
Optional
No; tree name is returned as root

Yes: passes the root part of treename.path form variable when cftree is submitted

No, or omitted: root level of form variable is not passed; path value starts with the first node

For the preserveData attribute of cfform to work with the tree, you must set this attribute to Yes.
If you specify a root name for a tree item with cftreeitem queryasroot, that value is returned. If you do not specify a root name, ColdFusion returns the query name as the root.

appendKey
Optional
Yes

Yes: when used with href, passes CFTREEITEMKEY variable with the value of the selected tree item in URL to the application page specified in the cfform action attribute

No

highlightHref
Optional
Yes

Yes: highlights links that are associated with a cftreeitem with a URL attribute value

No: disables highlight

onValidate
Optional

JavaScript function 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; False, otherwise.

message
Optional

Message to display if validation fails.

onError
Optional

JavaScript function to execute if validation fails.

lookAndFeel
Optional
windows

motif: renders slider in Motif style

windows: renders slider in Windows style

metal: renders slider in Java Swing style

If platform does not support style option, tag defaults to platform default style.

font
Optional

Font name for data in tree control.

fontSize
Optional

Font size for text in tree control, in points.

italic
Optional
No

Yes: displays tree control text in italics

No

bold
Optional
No

Yes: displays tree control text in bold

No

height
Optional
320
Tree control height, in pixels.

width
Optional
200
Tree control width, in pixels.

vSpace
Optional

Vertical margin above and below tree control, in pixels.

hSpace
Optional

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

align
Optional

top

left

bottom

baseline

texttop

absbottom

middle

absmiddle

right

border
Optional
Yes

Yes

No

hScroll
Optional
Yes

Yes: permits horizontal scrolling

No

vScroll
Optional
Yes

Yes: permits vertical scrolling

No

notSupported
Optional

Message to display if page that contains Java applet-based form control is opened by browser that does not support Java, or has Java support disabled. For example:
notSupported = " Browser must support Java to view ColdFusion Java Applets"
If no message is specified, this message displays:
Browser must support Java to view ColdFusion Java Applets!

Attribute	Req/Opt	Default	Description
name	Required		Name for tree control.
required	Optional	No	Yes: user must select an item in tree control No
delimiter	Optional	\\	Character to separate elements in form variable path.
completePath	Optional	No; tree name is returned as root	Yes: passes the root part of `treename.path` form variable when `cftree` is submitted No, or omitted: root level of form variable is not passed; path value starts with the first node For the `preserveData` attribute of `cfform` to work with the tree, you must set this attribute to Yes. If you specify a root name for a tree item with `cftreeitem` `queryasroot`, that value is returned. If you do not specify a root name, ColdFusion returns the query name as the root.
appendKey	Optional	Yes	Yes: when used with href, passes CFTREEITEMKEY variable with the value of the selected tree item in URL to the application page specified in the `cfform action` attribute No
highlightHref	Optional	Yes	Yes: highlights links that are associated with a `cftreeitem` with a `URL` attribute value No: disables highlight
onValidate	Optional		JavaScript function 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; False, otherwise.
message	Optional		Message to display if validation fails.
onError	Optional		JavaScript function to execute if validation fails.
lookAndFeel	Optional	windows	motif: renders slider in Motif style windows: renders slider in Windows style metal: renders slider in Java Swing style If platform does not support style option, tag defaults to platform default style.
font	Optional		Font name for data in tree control.
fontSize	Optional		Font size for text in tree control, in points.
italic	Optional	No	Yes: displays tree control text in italics No
bold	Optional	No	Yes: displays tree control text in bold No
height	Optional	320	Tree control height, in pixels.
width	Optional	200	Tree control width, in pixels.
vSpace	Optional		Vertical margin above and below tree control, in pixels.
hSpace	Optional		Horizontal spacing to left and right of tree control, in pixels.
align	Optional		top left bottom baseline texttop absbottom middle absmiddle right
border	Optional	Yes	Yes No
hScroll	Optional	Yes	Yes: permits horizontal scrolling No
vScroll	Optional	Yes	Yes: permits vertical scrolling No
notSupported	Optional		Message to display if page that contains Java applet-based form control is opened by 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>"` If no message is specified, this message displays: `<b>Browser must support Java to <br> view ColdFusion Java Applets!</b>`

Usage

This tag requires the client to download a Java applet. Downloading an applet takes time; therefore, using this tag might be slightly slower than using an HTML form element or the cfinput tag to get the same information.

For this tag to work properly. the browser must 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.

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. 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>
<body>
<h3>cftree Example</h3>
<!--- Use cfform when using other cfinput tools --->
<cfform action = "cftree.cfm">
<!--- Use cfselect to present the contents of the query by column --->
<h3>cfselect Presentation of Data</h3>
<h4>Click an employee's last name and "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>
...