<CFTREE> has been part of ColdFusion since CF2 - originally a Java applet, and then a Flash control, and in ColdFusion 8 an HTML tree control with powerful Ajax support. To demonstrate how to use the new HTML <CFTREE>, here is an example that will let you browse the file system tree on your server. What makes this an Ajax control is that the entire tree is not loaded on startup. Rather, it is loaded incrementally, minimal data is loaded on startup, and when a node is expanded an asynchronous call is made back to the server to obtain the children for that node, and so on. This improves performance (by not requiring that entire trees be loaded if they are not needed), and also simplifies actual tree data (formatting and parsing nested tree data is not pretty).
The client-side code for this example is really simple, as seen here:
<cfform>
<cftree name="dirtree" format="html">
<cftreeitem bind="cfc:dirtree.getDirEntries({cftreeitempath}, {cftreeitemvalue})">
</cftree>
</cfform>
This <CFTREE> uses a "bind" to point to a CFC method to obtain tree contents. When a binding is used, as it is here, only a single <CFTREEITEM> may be specified, and it is responsible for loading all data as needed. On initial tree load the CFC method is invoked (passing an empty string for the current path and value), and then as branches are expanded the CFC method is invoked again (passing the current path and value back to the server).
It is worth noting that, by default, results are cached on the client. So expanding and collapsing a branch repeatedly does not trigger multiple CFC method calls. Caching can be disabled if needed.
The CFC method that the <CFTREE> is bound to is shown here:
<!--- Get directory entries for Ajax CFTREE --->
<cffunction name="getDirEntries" access="remote" returnType="array">
<cfargument name="path" type="string" required="false" default="">
<cfargument name="value" type="string" required="false" default="">
<!--- Init variables --->
<cfset var dir="">
<cfset var entry="">
<cfset var result=arrayNew(1)>
<cfset var filepath="">
<!--- Check if top level --->
<cfif ARGUMENTS.value IS "">
<!--- Yes, top level, get drives --->
<cfset dir=getDrives()>
<!--- Loop through dir list --->
<cfloop query="dir">
<!--- Add each drive/root --->
<cfset entry=StructNew()>
<cfset entry.value=dir.name>
<cfset entry.display=dir.name>
<cfset entry.img="fixed">
<cfset ArrayAppend(result, entry)>
</cfloop>
<cfelse>
<!--- Not top level, get dir list --->
<cfdirectory action="list"
directory="#ARGUMENTS.value#"
name="dir"
sort="name">
<!--- Loop through dir list --->
<cfloop query="dir">
<!--- Create entry --->
<cfset entry=StructNew()>
<!--- Use full path as value --->
<cfset entry.value=ARGUMENTS.value & THIS.separator & dir.name>
<!--- Use just name for display --->
<cfset entry.display=dir.name>
<!--- Is this a file or a dir? --->
<cfif dir.type IS "file">
<!--- A file, so no children --->
<cfset entry.leafnode=TRUE>
<!--- Use document icon --->
<cfset entry.img="document">
<cfelse>
<!--- A dir, use folder icon --->
<cfset entry.img="folder">
<cfset entry.imgopen="folder">
</cfif>
<!--- Add it to the array --->
<cfset ArrayAppend(result, entry)>
</cfloop>
</cfif>
<!--- And return the results --->
<cfreturn result>
</cffunction>
<CFTREE> expects the bound CFC method to return an array of entries represented as structures. These structures should, at a minimum, contain two members - "display" is the string to be displayed in the tree, and "value" is the value to be returned (back to the bound CFC when branches are expanded, as well as when the form containing the <CFTREE> is actually submitted). The structures may also contain additional members (equivalent to the attributes supported by <CFTREEITEM>), for example, "img" and "imgopen". One important optional member is "leafnode" which tells the tree whether or not the current entry is a leaf (has no children) or a branch (could have children). As tree data is loaded as needed, <CFTREE> can't know if a branch has children until the user tries to expand it. In this example we want folders to be expandable, but not files, and so <leafnode> is set to "true" for file entries.
If the method is being invoked for the top level of the tree (in which case ARGUMENTS.value will be an empty string) then a function is called to get all system drives (or roots). The code then loops through the results, creating a structure for each, and appending these to a results array. If the method is being invoked for a child branch (in which case ARGUMENTS.value will contain the path to the branch that was expanded), <CFDIRECTORY> is used to obtain the contents of that folder, and then the results are looped over, creating a structure for each entry, and again appending these to a results array.
This example returns all file and folders. If you wanted to return a subset of data, perhaps to allow the user to find files of a specific type, you'd just need to modify the <CFDIRECTORY>, possibly replacing it with two <CFDIRECTORY> calls, one for folders and one for the files (using a filter to select just the files you want).
This method refers to a function named getDrives() (to obtain drives or roots) and a variable named THIS.separator (used to refer to the OS specific path separator character), both of which need to be defined. The following is the complete dirtree.cfc, containing the previously seen getDirEntries() method, as well as all supporting code:
<cfcomponent output="false">
<!--- Constructor code --->
<cfset THIS.separator=getPathSeparator()>
<!--- Get system path separator character --->
<cffunction name="getPathSeparator" access="private" returntype="string">
<!--- Init variables --->
<cfset var jifObj="">
<!--- Need java.io.File class --->
<cfobject type="java" class="java.io.File" name="jifObj">
<!--- Return seperator --->
<cfreturn jifObj.separator>
</cffunction>
<!--- Get system drives (or roots) --->
<cffunction name="getDrives" access="private" returntype="query">
<!--- Init variables --->
<cfset var jifObj="">
<cfset var drives="">
<cfset var i=0>
<cfset var result=QueryNew("name")>
<!--- Need java.io.File class --->
<cfobject type="java" class="java.io.File" name="jifObj">
<!--- Get drives/roots --->
<cfset drives=jifObj.listRoots()>
<!--- Loop through results and create query --->
<cfloop from="1" to="#ArrayLen(drives)#" index="i">
<cfset QueryAddRow(result)>
<cfset QuerySetCell(result, "name", drives[i].toString())>
</cfloop>
<!--- Return results --->
<cfreturn result>
</cffunction>
<!--- Get directory entries for Ajax CFTREE --->
<cffunction name="getDirEntries" access="remote" returnType="array">
<cfargument name="path" type="string" required="false" default="">
<cfargument name="value" type="string" required="false" default="">
<!--- Init variables --->
<cfset var dir="">
<cfset var entry="">
<cfset var result=arrayNew(1)>
<cfset var filepath="">
<!--- Check if top level --->
<cfif ARGUMENTS.value IS "">
<!--- Yes, top level, get drives --->
<cfset dir=getDrives()>
<!--- Loop through dir list --->
<cfloop query="dir">
<!--- Add each drive/root --->
<cfset entry=StructNew()>
<cfset entry.value=dir.name>
<cfset entry.display=dir.name>
<cfset entry.img="fixed">
<cfset ArrayAppend(result, entry)>
</cfloop>
<cfelse>
<!--- Not top level, get dir list --->
<cfdirectory action="list"
directory="#ARGUMENTS.value#"
name="dir"
sort="name">
<!--- Loop through dir list --->
<cfloop query="dir">
<!--- Create entry --->
<cfset entry=StructNew()>
<!--- Use full path as value --->
<cfset entry.value=ARGUMENTS.value & THIS.separator & dir.name>
<!--- Use just name for display --->
<cfset entry.display=dir.name>
<!--- Is this a file or a dir? --->
<cfif dir.type IS "file">
<!--- A file, so no children --->
<cfset entry.leafnode=TRUE>
<!--- Use document icon --->
<cfset entry.img="document">
<cfelse>
<!--- A dir, use folder icon --->
<cfset entry.img="folder">
<cfset entry.imgopen="folder">
</cfif>
<!--- Add it to the array --->
<cfset ArrayAppend(result, entry)>
</cfloop>
</cfif>
<!--- And return the results --->
<cfreturn result>
</cffunction>
</cfcomponent>
As you can see, once you get your arms around how data is formatted and passed back and forth, the new Ajax enabled HTML based <CFTREE> is both powerful and really easy to use.
i've tried this tutorial using cf9 and i went over a little, let's call it feature ;D
if u're trying to open a tree-item thats indeed a dvddrive or a floppydrive, the javascript crashed (at least i think its a javascript, haven't really looked at it yet)
so just wanted to come back to you with a little bugreport
hope you're doing fine, keep up the good work, couple of your tutorials really got me off the slack :)