cftree

Last updated on Apr 27, 2021 06:08:00 AM GMT | Also Applies to ColdFusion

FORMAT="applet" HAS BEEN DEPRECATED

The UI tags for cftree based on the YUI toolkit have been deprecated.

For a full list of deprecated features, refer to Deprecated features.

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.

Syntax

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>

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

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

Note:

In XML format, ColdFusion passes all attributes to the XML. The supplied XSLT skins do not handle or display XML format trees, but do display applet and Flash format trees.

Attribute	Req/OptFormat	Default	Description
name	Required;All		Name for a tree control.
align	Optional;Applet, object		top left bottom baseline texttop absbottom middle absmiddle right
appendKey	Optional;All	yes	yes: if you use cftreeitem href attributes, ColdFusion appends a CFTREEITEMKEY query string variable with the value of the selected tree item to the cfform action URL. no: does not append the tree item value to the URL.
bold	Optional;Applet, Flash, HTML	no	yes: displays tree control text in bold. no
border	Optional;Applet, object	yes	yes: displays a border around the tree control. no
cache	Optional;HTML	yes	Applies only if the tree's child treeitem tag uses a bind expression. A Boolean value that specifies whether to get new data each time the user expands tree nodes, as follows: yes: fetches a node's child items only once, when the node is first expanded no: fetches child items each time the node is expanded.
completePath	Optional;Applet, HTML, object	no	yes: starts the Form.treename.path variable with the root of the tree path when cftree is submitted. no: omits the root level from the Form.treename.path variable; the value starts with the first child node in the tree. For the preserveData attribute of cfform to work with the tree, set this attribute to yes. For tree items populated by a query, if you use the cftreeitem queryasroot attribute to specify a root name, that value is returned. If you do not specify a root name, ColdFusion returns the query name.
delimiter	Optional;All	{{\\\\}}	Character to separate elements in the Forms.treename.path variable of the action page.
enabled	Optional;Flash	yes	Flash format only: Boolean value that specifies whether the control is enabled. A disabled control appears in light gray.
font	Optional;Applet, HTML		Font name for text in the tree control.
fontSize	Optional;Applet, Flash, HTML		Font size for text in the tree control, in pixels.
format	Optional;All	applet	applet: displays the tree using a Java applet in the browser. flash: displays the tree using a Flash control html: displays the tree uses Ajax-based HTML object: returns the tree as a ColdFusion structure with the name specified by the name attribute, For details of the structure contents, see the section object format. xml: generates an XML representation of the tree. In XML format forms, includes the generated XML in the form. In HTML format forms, puts the XML in a string variable with the name specified by the name attribute.
height	Optional;Applet, Flash	320(applet only)	Tree control height, in pixels. If you omit this attribute in Flash format, Flash automatically sizes the tree.
highlightHref	Optional;Applet, Object	yes	yes: highlights as a link the displayed value for any cftreeitem tag that specifies an href attribute. no: disables highlighting.
hScroll	Optional;Applet, object	yes	yes: permits horizontal scrolling. no
hSpace	Optional;Applet		Horizontal spacing to left and right of tree control, in pixels.
italic	Optional;Applet, Flash, HTML	no	yes: displays tree control text in italics. no
label	Optional;HTML,
lookAndFeel	Optional;Applet, object	windows	motif: renders the tree in Motif style. windows: renders the tree in Windows style. metal: renders the tree in Java Swing style. If the platform does not support a style option, the tag uses the default style for the platform.
message	Optional;Applet, HTML		Message to display if validation fails.
notSupported	Optional;Applet	See Description	Text to display if a page that contains a Java applet-based cfform control is opened by a browser that does not support Java or has Java support disabled, for example;"<b> Browser must support Java to view ColdFusion Java Applets</b>"}}Default message:{{<b>Browser must support Java to <br>view ColdFusion Java Applets!</b>
onBlur	Optional;Flash		ActionScript to run when the tree loses focus.
onChange	Optional;Flash		ActionScript to run when the control changes due to user action. If you specify an onChange event handler, the Form scope of the ColdFusion action page does not automatically get information about selected items. The ActionScript onChange event handler must handle all changes and selections.
onError	Optional;Applet, HTML		A JavaScript function to run if validation fails.
onFocus	Optional;Flash		ActionScript to run when the tree gets focus. The JavaScript DOM form object, value of the name attribute, value that failed validation, and any error text specified by the message attribute are passed to the method.
onValidate	Optional;Applet, HTML		JavaScript function to validate user input. The JavaScript DOM form object, input object, and input object value are passed to the specified routine, which must return true if validation succeeds; false, otherwise.
required	Optional;Applet, Flash, HTML	no	yes: users must select an item in the tree control. no
style	Optional;Flash, HTML		Must be a style specification in CSS format. In HTML format, this attribute corresponds to the value of an HTML style attribute. In Flash format, use the same syntax and contents as used in Flex for the corresponding Flash element.
tooltip	Optional;Flash		Flash format only: Text to display when the mouse pointer hovers over the control.
value	Optional;HTML,
visible	Optional;Flash	yes	Flash format only: Boolean value that specifies whether to show the control. Space that would be occupied by an invisible control is blank.
vScroll	Optional;Applet, object	yes	yes: permits vertical scrolling. no
vSpace	Optional;Applet		Vertical margin above and below tree control, in pixels.
width	Optional;Applet, Flash	200 (applet only)	Tree control width, in pixels. If you omit this attribute in Flash format, Flash automatically sizes the tree.

Note:

All attributes are passed to the XML generated in XML format, but no ColdFusion skin interprets cftree XML.

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.

Note:

If you specify Flash format for this tag in an HTML format form, and you do not specify height and width attributes, Flash takes up more than the remaining visible area on the screen. If any other output follows the tree, including any form controls, users must scroll to see it. Therefore, if you follow a Flash tree in an HTML form with additional output, specify height and width values.

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 formFor 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:

Field	Value
path	The path through the tree to the selected node, in the form [root]node_1_node_2_\.... In applet format, the path includes the root node only if the completePath attribute is true. In Flash format, the path always includes the root node.
node	The value of the selected tree node.

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.

Note:

If you specify an object format tree in an XML format form, ColdFusion does not generate the 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:

align	completePath	highlightHref	lookAndFeel
appendKey	delimiter	hScroll	name
bold	fontWeight	italic	vscroll
border

Children array

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

Field	Value
children	This item's child items; an array of item structures.
display	Tree item label, as determined by the cftreeitem display attribute.
expand	Whether to expand the item to display any children; value of cftreeitem expand attribute.
href	The URL to link to when the user selects the item; value of the cftreeitem href attribute.
img	The tree image icon Image to display as an icon for the tree item; value of cftreeitem img attribute. You can use the img attribute to display custom icons only in the Applet version; not in the Flash version.
imgOpen	Image to display when the tree item is open (expanded); value of cftreeitem imgopen attribute.
parent	Value of this item's parent item in the tree.
path	The node path from the tree root to the current element.
queryAsRoot	Whether the query is the root of the item; value of cftreeitem queryAsRoot attribute.
target	The link target, such as _blank; value of the item's cftreeitem target attribute.
value	The item's value, as determined by the cftreeitem value attribute.

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.

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.

<!--- 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>

Legal Notices | Online Privacy Policy

cftree

FORMAT="applet" HAS BEEN DEPRECATED

Description

Category

Syntax

See also

History

Attributes

Usage

Form variables

object format

Attribute settings

Children array

Example

Ask the Community

Contact Us