cfdirectory

Description

Manages interactions with directories.

Syntax

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

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:

Code such as the following, which was acceptable in earlier releases, may cause incorrect output in ColdFusion MX:

<cfdirectory action = "list" directory ="c:\" name="foo>
Files in c:\<br>
<cfloop query = "foo" startrow = 3>
  #name#<br>
>

Code such as the following, which was acceptable in earlier releases, is acceptable in ColdFusion MX, although it is unnecessary:

<cfdirectory directory="c:\" name="foo">
Files in c:\<br>
<cfoutput query="foo"> 
  <cfif NOT foo.name is "." AND NOT foo.name is "..">  
    #name#<br>
  </cfif>
</cfoutput>

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

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:

name: directory entry name. The entries "." and ".." are not returned.
size: directory entry size
type: file type: File, for a file; Dir, for a directory
dateLastModified: the date that an entry was last modified
attributes: file attributes, if applicable
mode: (UNIX and Linux only) see the UNIX man pages, chmod shell command.

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>