ColdFusion Ajax Tutorial 5: File System Browsing With The Tree Control

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

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:

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

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.