|
cftreeitem
DescriptionPopulates
a form tree control, created with the cftree tag,
with one or more elements.
Syntax<cftreeitem
value = "text"
bind = "bind expression"
display = "text"
expand = "yes|no"
href = "URL"
img = "filename"
imgopen = "filename"
parent = "parent name"
query = "queryname"
queryAsRoot = "yes|no"
target = "URL target">
OR
<cftreeitem
bind = "bind expression">
onBindError = "JavaScript function name"
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.
HistoryColdFusion
8: Added the bind and onBindError attributes.
AttributesNote: 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/Opt;
Format
|
Default
|
Description
|
value
|
Required for applet, Flash, XML.
value or bind is required
for HTML.
|
|
Value passed when the form containing the
tree 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.
|
bind
|
value or bind is required
for HTML
|
|
A bind expression specifying a CFC function,
JavaScript function, or URL that dynamically gets all tree nodes.
You can use this attribute only at the top level of the tree, and
in this case, the tree can have only cftreeitem tag.
If
you use the bind attribute, the only other allowed
attribute is onBindError.
For details creating
trees that using binding, see Using
HTML trees in the Developing ColdFusion Applications
|
display
|
Optional;
All
|
value
|
Tree item label. When populating a tree
with data from a query, specify names in a delimited list, for example:
display = "dept_name,emp_name"
|
expand
|
Optional;
All
|
yes
|
|
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"
|
img
|
Optional;
Applet, HTML, 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"
You
can also specify a path relative to the web root.
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, HTML, object
|
|
Icon displayed with open tree item, as described
for the img attribute.
|
onBindError
|
Optional;
HTML
|
see Description
|
The name of a JavaScript function to execute
if evaluating a bind expression results in an error. The function
must take two attributes: an HTTP status code and a message.
If
you omit this attribute, and you specified a global error handler
(by using the ColdFusion.setGlobalErrorHandler function),
it displays the error message; otherwise a default error pop-up
appears.
|
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.
|
query
|
Optional;
All
|
|
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 lets you 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.
|
target
|
Optional;
All
|
|
Target attribute of href URL.
When populating a tree with data from a query, specify targets in
a comma-delimited list, for example:
target = "FRAME_BODY,_blank"
|
UsageFor this
tag to work properly. the browser must be JavaScript-enabled. This
tag must be a child of a cftree tag.
The cftreeitem tag
has three basic formats:
If you do not use a query or bind attribute
to populate this tag, it creates a single tree item.
If you use a query, it creates multiple
items; each row of the query creates a hierarchically nested set
of items with one item per column.
If you use the bind attribute, the client
side tree dynamically gets the data for the tree item’s immediate
children, and creates the child items, when a tree item expands.
For detailed information on using the bind attribute
to populate an HTML format tree, see Using
HTML trees in the Developing ColdFusion Applications.
ExampleThe
following example creates a simple tree by 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 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>
|