cftreeitem

Description

Populates a form tree control, created with the cftree tag, with one or more elements.

Syntax

<cftreeitem 
   value = "text"
   display = "text"
   parent = "parent_name"
   img = "filename"
   imgopen = "filename"
   href = "URL"
   target = "URL_target"
   query = "queryname"
   queryAsRoot = "yes" or "no"
   expand = "yes" or "no">

Attributes

Note: In XML format, ColdFusion MX 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/Opt; Format	Default	Description
value	Required; All		Value passed when `cfform` is submitted. When populating a tree with data from a `cfquery`, you can specify multiple columns to use in a delimited list; for example, `value` `=` `"dept_id,emp_id"`. In this case, each column generates an item that is a child of the column that precedes it in the list.
display	Optional; All	value	Tree item label. When populating a tree with data from a query, specify names in a delimited list. Example: `display` `=` `"dept_name,emp_name"`
parent	Optional; All		Value of the tree item parent. Determines the item's placement in the tree hierarchy. If omitted, the item is placed at the tree root level, or if the `queryAsRoot` attribute is True, directly under the query.
img	Optional; Applet, object	folder	Image name, filename, or file URL for tree item icon. The following values are provided: cd computer document element folder floppy fixed remote You can also specify a custom image. To do so, include path and file extension; for example: `img = "../images/page1.gif"` Custom images are not supported for Flash format. To specify more than one image in a tree, or an image at the second or subsequent level, use commas to separate names, corresponding to level; for example: `img = "folder,document"` `img = ",document" (example of second level)`
imgopen	Optional; Applet, object		Icon displayed with open tree item, as describe for the `img` attribute.
href	Optional; All		URL to link to if the user clicks the tree item. If you use a `query` attribute, the `href` attribute can specify a query column that contains URLs. If `href` is not a query column, the attribute text must be a URL or list of URLs. When populating a tree with data from a query, specify the URLs in a comma-delimited list; for example: `href = "http://dept_svr,http://emp_svr"`
target	Optional; All		Target attribute of `href` URL. When populating a tree with data from a query, specify target in delimited list: `target = "FRAME_BODY,_blank"`
query	Optional; Applet, Flash		Query name to use to populate the treeitem. ColdFusion generates an item for each field value in the query column list specified by the `value` attribute. The fields in each row are hierarchically linked to the first column.
queryAsRoot	Optional; All	Yes	Applies only if you specify a `query` attribute. Defines the query as the root level for all items generated by this tag. This attribute enables you to avoid creating a parent `cftreeitem`. Yes: generates a parent (root) item for all other items generated by the tag, with the query name as its value; if you specify a `parent` attribute, the root item is a child of the specified parent. No: uses the item specified by the `parent` attribute as the immediate parent of all items generated by this tag. If there is no `parent` attribute, use the query as the parent. A string: creates a root item and uses the specified string as the item name; if you specify a `parent` attribute, the root item is a child of the specified parent.
expand	Optional; All	Yes	Yes: expands tree to show tree item children. No: keeps tree item collapsed.

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 you do not use a query to populate this tag, it creates a single tree item. If you do use a query, it creates multiple items; each row of the query creates a hierarchically nested set of items with one item per column.

Example

The following example creates a simple tree using a single cftreeitem tag and a query:

<cfform action = "#cgi.script_name#">
   <cftree name = "Employees" height = "400" width = "200">
      <cftreeitem value="LastName, FirstName, Emp_ID" query="getEmployees"
       queryAsRoot="False">
   </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 can click the + signs to display additional information. If you click the employee name, ColdFusion links back to the same page and displays the selected employee's ID.

<!--- 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>cftreeitem 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("URL.user_ID")>
   <cfoutput>
      <!--- URL.cftreeitemkey is the selected tree item's value attribute. --->
      You Requested information on #URL.cftreeitemKey#; User ID #URL.user_ID#
   </cfoutput>
   <br><br>
</cfif>
<!--- Display the tree. The cftree tag must be in a cfform. --->
<cfform>
   <cftree name = "Employees" height = "400" width = "200" 
      font = "Arial Narrow" highlighthref="No" hscroll="No"> 
      <!--- 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#" 
               display = "#LastName#, #FirstName#"
               parent = "#Department#" expand="no"
               href="#cgi.script_name#?user_id=#emp_id#">
            <!--- Each Employee entry has ID and ContactInfo children. --->
            <cftreeitem value = "#Emp_ID#" display = "Employee ID: #Emp_ID#" 
               parent = "#LastName#, #FirstName#">
            <!--- Each node must be unique value, so use Emp_ID om value. --->
            <cftreeitem value = "#Emp_ID#_ContactInfo" 
               display = "Contact Information" 
               parent = "#LastName#, #FirstName#" expand = "No">
            <!--- ContactInfo has two children. --->
            <cftreeitem value = "#Phone#" parent = "#Emp_ID#_ContactInfo">
            <cftreeitem value = "#Email#" parent = "#Emp_ID#_ContactInfo">
         </cfoutput>
      </cfoutput>
   </cftree>
</cfform>

View comments in LiveDocs