View comments | RSS feed
CFML Reference Previous Up One Level Next
ColdFusion Tags


cfdirectory

Description

Manages interactions with directories.

Category

File management tags

Note:   For this tag execute, it must be enabled in the ColdFusion Administrator. For more information, see Administering ColdFusion MX.

If you put ColdFusion applications on a server that is used by multiple customers, you must consider the security of files and directories that could be uploaded or otherwise manipulated with this tag by unauthorized users. For more information about securing ColdFusion tags, see Administering ColdFusion MX.

Syntax 

<cfdirectory 
  action = "directory action"
  directory = "directory name"
  name = "query name"
  filter = "list filter"
  mode = "permission"
  sort = "sort specification"
  newDirectory = "new directory name">

See also

cffile

History

New in ColdFusion MX: On Windows, if cfdirectory action = "list", this tag does not return the directory entries "." (dot) or ".." (dot dot), which represent "the current directory" and "the parent directory." (In earlier releases, ColdFusion returned these entries.)

New in ColdFusion MX:

Attributes

Attribute Req/Opt Default Description
action
 Optional
 List
  • list: returns a query record set of the files in the specified directory. The directory entries "." (dot) and ".." (dot dot), which represent the current directory and the parent directory, are not returned.
  • create
  • delete
  • rename
directory
 Required
Absolute pathname of directory against which to perform action.
name
 Required if action = "list"
Name for output record set.
filter
 Optional if action = "list"
File extension filter applied to returned names. For example: *.cfm. One filter can be applied.
mode
 Optional
Used with action = "create". Permissions. Applies only to Solaris and HP-UX. Octal values of chmod command. Assigned to owner, group, and other, respectively. For example:
  • 644: Assigns read/write permission to owner; read permission to group and other
  • 777: Assigns read/write/execute permission to all
sort
 Optional; used if action = "list"
 ASC
 Query column(s) by which to sort directory listing. Delimited list of columns from query output.
To qualify a column, use:
  • ac: ascending (a to z) sort order
  • desc: descending (z to a) sort order
For example:
sort = "dirname ASC, file2 DESC, size, datelastmodified"
newDirectory
 Required if action = "rename"
New name for directory

Usage

If action = "list", cfdirectory returns these result columns, which you can reference in a cfoutput tag:

You can use the following result columns in standard CFML expressions, preceding the result column name with the query name: 

#mydirectory.name#

#mydirectory.size#
#mydirectory.type#
#mydirectory.dateLastModified#
#mydirectory.attributes#
#mydirectory.mode#

Example 

<h3>cfdirectory Example</h3>
<!--- use cfdirectory to give the contents of the snippets directory, 
order by name and size (you may need to modify this path) --->
<cfdirectory 
  directory="#GetDirectoryFromPath(GetTemplatePath())#" 
  name="myDirectory" 
  sort="name ASC, size DESC">
<!---- Output the contents of the cfdirectory as a cftable -----> 
<cftable 
  query="myDirectory" 
  htmltable 
  colheaders> 
  <cfcol 
    header="NAME:" 
    text="#Name#"> 
  <cfcol 
    header="SIZE:" 
    text="#Size#"> 
</cftable>
Previous Up Next

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | Bug Reporting

Version 6

Comments are no longer accepted for ColdFusion MX. ColdFusion 8 is the current version.

Comments


hlichtin said on Jan 28, 2003 at 3:31 PM :
A quick test shows cfdirectory working with UNC and mapped drives, but that you have to be careful that you have the correct access permissions. When I ran CFMX as a Windows Service, I wasn't getting any results when I used cfdirectory to list a remote directory because CFMX runs as System and Windows file sharing wasn't allowing access to System.
aeverett said on Aug 26, 2002 at 7:54 PM :
It seems that CFDIRECTORY can't work with mapped network drives or even UNC mappings.
Alex Peterson said on Aug 18, 2003 at 11:43 AM :
ac: ascending (a to z) sort order is a typo. It should be "ASC" for ascending order.
sean9999 said on Sep 23, 2003 at 12:20 PM :
it would be nice to know how to use the 'filter' attribute to EXCLUDE certain files or file types.

For instance, if i wanted to list all the files in a directory that WERE NOT .CFM files, or were not specifically application.cfm, heaeder.cfm (or whatever)...

One could of course filter them out after the fact during the cfoutput block, but it would be preferable to do it at the beginning
ReganEngamn said on Jan 9, 2004 at 5:03 PM :
Well cfdirectory used to do what I wanted it to and now it doesn't. I want to list the files dynamically in the current directory...
to bad you can't use "." or ".." in for the directory attribute
tobylaroni said on May 18, 2005 at 10:58 AM :
IMPORTANT NOTE (esp. important for coders using Fusebox):
If you are inside a loop (using cfoutput or cloop) of a query generated by CFDIRECTORY, you *cannot* use the attributes scope! This is because within the loop. "attributes" is the name of one of the fields returned by CFDIRECTORY. If you're in a CFDIRECTORY loop and you try to set the value of, say, attributes.person_id, you will encounter genuinely odd errors like:

You have attempted to dereference a scalar variable of type class coldfusion.sql.QueryColumn as a structure with members.

or

The value "person_id" cannot be converted to a number.

SOLUTION: a) don't use the attributes scope within the loop. b) if you need to use the attributes scope, either use QueryNew to construct a query using the results from CFDIRECTORY, or use Query of a Query and only pull in the name, datelastmodified, and type fields (for some reason, you can't retrieve the size field when doing a query of a query). Then, loop through this constructed query.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/6/CFML_Reference/Tags-pt121.htm