Learning ColdFusion 8: CFDirectory Improvements
Posted August 1, 2007 at 8:10 AM
In addition to all the new tags and functions that ColdFusion 8 has added to the already amazing language that we have come to love, ColdFusion 8 has also made very nice improvements to the existing feature set. Among those are updates to the CFDiretory tag. While the ColdFusion CFDirectory can Create, Rename, Delete, and List directories, the ColdFusion 8 updates were made only to the listing action.
New to the CFDirectory tag are the attributes ListInfo and Type. ListInfo determines what columns are returned in the CFDirectory query object. The valid values for this attribute are "all", the default, and "name". When the ListInfo attribute is set to "all", all the directory and file names are returned in the query just like a CFMX 7 CFDirectory tag. So for instance, a ColdFusion 7 CFDirectory tag:
Launch code in new window » Download code as text file »
- <!---
- List out all directories and images in
- the data directory.
- --->
- <cfdirectory
- action="list"
- directory="#ExpandPath( './data/' )#"
- recurse="true"
- name="qFile"
- />
-
- <!--- Dump out file query. --->
- <cfdump
- var="#qFile#"
- label="CFDirectory - CFMX 7 Compliant"
- />
... will return a query that looks like this:
| | | | ||
| |  | | ||
| | | |
The above query is the equivalent of running the CFDirectory with ListInfo="all"; however, now, if we run the same CFDirectory tag, but this time, tell it to only list out the "name":
Launch code in new window » Download code as text file »
- <!---
- List out all directories and images in the data
- directory. This time, however, only list out the
- names of the files and directories.
- --->
- <cfdirectory
- action="list"
- directory="#ExpandPath( './data/' )#"
- recurse="true"
- listinfo="name"
- name="qFile"
- />
-
- <!--- Dump out file query. --->
- <cfdump
- var="#qFile#"
- label="CFDirectory - Name Only"
- />
... we will get a query that looks like this:
| | | | ||
| |  | | ||
| | | |
Notice here that we are getting only the Name column of the query. However, also notice that the data in the Name column is not exactly the same of the name column in the CFMX 7 compliant query. While the CFMX 7 CFDirectory query put only the file name or directory name in the Name column, the ColdFusion 8 CFDirectory name-only query basically includes the path of the files relative to the root directory we are targeting.
This demo was run during the ColdFusion 8 beta. I have not had a chance to install the official ColdFusion 8 Developer edition yet. It is possible that this may have changed in the official release. My guess, however, is that this was a design decision that was made to make the name-only query more useful. Afteral, a name-only query that had non sense of path structure would not be all that useful with any kind of recursive CFDirectory action. And, think about it - if it wasn't recursive, then you wouldn't have the directory structure at all since all files would be in the root of the target directory. Good call Adobe!
Listing only the name column can have significant performance increases and should be used whenever you don't need the rest of the information returned in CFDirectory.
The Type attribute of the ColdFusion 8 CFDirectory tag determines what type of items are returned in the resultant query. The valid values for this attribute are "file", "dir", and "all. All, the default value, means that both files and directories will be returned. The value "File" means that only files will be returned in the query. The value "Dir" means only directories will be returned in the query.
Running this code with the Type="file" attribute:
Launch code in new window » Download code as text file »
- <!--- List out all files in the data directory. --->
- <cfdirectory
- action="list"
- directory="#ExpandPath( './data/' )#"
- recurse="true"
- listinfo="name"
- type="file"
- name="qFile"
- />
-
- <!--- Dump out file query. --->
- <cfdump
- var="#qFile#"
- label="CFDirectory - Files Only"
- />
... we will get a query that looks like this:
| | | | ||
| |  | | ||
| | | |
Notice that the "images" and "documents" entries we saw earlier are no long present. These were directories and are being excluded from the resultant query. To me, this is an awesome feature because it saves us from having to run a ColdFusion query of queries, checking Type columns during output, or using Filter attribute hacks (*.*).
Similary, running this code with the Type="dir" attribute:
Launch code in new window » Download code as text file »
- <!--- List out all directories in the data directory. --->
- <cfdirectory
- action="list"
- directory="#ExpandPath( './data/' )#"
- recurse="true"
- listinfo="name"
- type="dir"
- name="qFile"
- />
-
- <!--- Dump out file query. --->
- <cfdump
- var="#qFile#"
- label="CFDirectory - Directories Only"
- />
... we will get a query that looks like this:
| | | | ||
| |  | | ||
| | | |
Notice that now, the only entries we have are the two directories, "documents" and "images".
ColdFusion 8 is so awesome, not only for all the new tags and functions, but also for all these little updates to existing features that are going to make our lives as developers so much easier.
Download Code Snippet ZIP File
Post Comment | Ask Ben | Permalink | Other Searches | Print Page
Newer Post
REListFind() ColdFusion User Defined Function
Older Post
Favorite Folders In HomeSite (Thanks John Elliott!)
Reader Comments
Just a heads up Ben that listinfo is available in CF7 but was an undocumented feature. I'm not sure though if its available in any earlier release than CF7. It's a great attribute if you just need filenames since thats all I've ever used cfdirectory for so the performance boost is very nice.
So they still don't have the created date information. I think this was request ages ago.
@Javier,
Yeah, I have seen it used unofficially in ColdFusion MX7, but I never used it personally. But, now that it is documented and publicly known, I am sure I will start to make use of it.
@Tony,
Sorry :(
One more thing that I was expecting to be there in CF8 is the folder/directory size
but it seems that still I need to use java to do that.
:(
Awesome post Ben!
I tested this in CF8 and my cfdirectory query is giving me just the filename, rather than the relative path to the file from the calling page like in your example... it's behaving just like you showed CF7 used to handle the "name" at the top of your post. And this is with listinfo="name" set in the cfdirectory tag.
Is this just happening for me, or have you had a chance to test in the official version of CF8?
Cheers, Fitz
