|
cfdirectory
DescriptionManages
interactions with directories.
Syntax<cfdirectory
directory = "directory name"
action = "list|create|delete|rename"
filter = "list filter"
listInfo = "name|all"
mode = "permission"
name = "query name"
newDirectory = "new directory name"
recurse = "yes|no"
sort = "sort specification"
type = "file|dir|all">
Note: You can
specify this tag’s attributes in an attributeCollection attribute
whose value is a structure. Specify the structure name in the attributeCollection attribute
and use the tag’s attribute names as structure keys.
HistoryColdFusion
8: Added the listinfo and type attributes.
ColdFusion
MX 7: Added the recurse attribute and directory result‑set column.
ColdFusion
MX:
Changed behavior for action = "list": On Windows, cfdirectoryaction = "list" no
longer returns the directory entries "." (dot)
or ".." (dot dot), which represent "the current directory"
and "the parent directory."
On Windows, cfdirectoryaction = "list" no
longer returns the values of the Archive and System attributes.
On UNIX and Linux, cfdirectoryaction = "list" does
not return any information in the mode column.
Attributes
Attribute
|
Req/Opt
|
Default
|
Description
|
directory
|
Required
|
|
Absolute pathname of directory against which
to perform action.
You can use an IP address, as in the following
example:
<cfdirectory directory="//12.3.123.123/c_drive/" name="dirQuery" action="LIST">
|
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
|
filter
|
Optional if action = "list"
|
|
File extension filter applied to returned
names, for example, *.cfm. One filter can be applied.
|
listinfo
|
Optional
|
all
|
|
mode
|
Optional
|
|
Used with action = "create".
Permissions. Applies only to UNIX and Linux. Octal values of chmod command.
Assigned to owner, group, and other, respectively, for example:
|
name
|
Required if action = "list"
|
|
Name for output record set.
|
newDirectory
|
Required if action = "rename"
|
|
New name for directory.
|
recurse
|
Optional
|
no
|
Whether ColdFusion performs the action on
subdirectories:
Valid for action="list" and action="delete".
|
sort
|
Optional; used if action = "list"
|
ASC
|
Query columns by which to sort a directory
listing. Delimited list of columns from query output.
To
qualify a column, use one of the following values:
For
example:
sort = "directory ASC, size DESC, datelastmodified"
|
type
|
Optional
|
all
|
file: includes
only filenames.
dir: includes only directory names.
all: includes both filenames and directory
names.
|
UsageIf 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 Configuring and Administering ColdFusion.
If action = "list", cfdirectory returns
the following result columns, which you can reference in a cfoutput tag:
name: Directory entry name. The entries "." and ".." are
not returned.
directory: Directory that contains the entry.
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: Empty column; retained for backward
compatibility with ColdFusion 5 applications on UNIX.
Use
the following result columns in standard CFML expressions, preceding
the result column name with the query name:
#mydirectory.name#
#mydirectory.directory#
#mydirectory.size#
#mydirectory.type#
#mydirectory.dateLastModified#
#mydirectory.attributes#
#mydirectory.mode#
Note: If the cfdirectory tag
does not appear to work, for example, if a list operation returns
an empty result set, make sure that you have correct permissions
to access the directory. For example, if you run ColdFusion as a
service on Windows, it operates by default as System, and cannot
access directories on a remote system or mapped drive; to resolve
this issue, do not run ColdFusion using the local system account.
The filter attribute
specifies a pattern of one or more characters. All names that match
that pattern are included in the list. On Windows systems, pattern matching
ignores text case, on UNIX and Linux, pattern matches are case-sensitive.
The
following two characters have special meaning in the pattern and
are called metacharacters:
The
following table shows examples of patterns and filenames that they
match:
Pattern
|
Matches
|
foo.*
|
Any file called foo with any extension;
for example, foo.html, foo.cfm, and foo.xml.
|
*.html
|
All files with the suffix .html, but not
files with the suffix .htm.
|
??
|
All files with two-character names.
|
Example<!--- EXAMPLE 1: Creating and Renaming
Check that the directory exists to avoid getting a ColdFusion error message. --->
<cfset newDirectory = "otherNewDir">
<cfset currentDirectory = GetDirectoryFromPath(GetTemplatePath()) & "newDir">
<!--- Check whether the directory exists. --->
<cfif DirectoryExists(currentDirectory)>
<!--- If yes, rename the directory. --->
<cfdirectory action = "rename" directory = "#currentDirectory#"
newDirectory = "#newDirectory#" >
<cfoutput>
<p>The directory existed and the name has been changed to: #newDirectory#</p>
</cfoutput>
<cfelse>
<!--- If no, create the directory. --->
<cfdirectory action = "create" directory = "#currentDirectory#" >
<cfoutput><p>Your directory has been created.</p></cfoutput>
</cfif>
<!--- EXAMPLE 2: Deleting a directory
Check that the directory exists and that files are not in the directory to avoid getting ColdFusion error messages. --->
<cfset currentDirectory = GetDirectoryFromPath(GetTemplatePath()) & "otherNewDir">
<!--- Check whether the directory exists. --->
<cfif DirectoryExists(currentDirectory)>
<!--- If yes, check whether there are files in the directory before deleting. --->
<cfdirectory action="list" directory="#currentDirectory#"
name="myDirectory">
<cfif myDirectory.recordcount gt 0>
<!--- If yes, delete the files from the directory. --->
<cfoutput>
<p>Files exist in this directory. Either delete the files or code
something to do so.</P>
</cfoutput>
<cfelse>
<!--- Directory is empty - just delete the directory. --->
<cfdirectory action = "delete" directory = "#currentDirectory#">
<cfoutput>
<p>The directory existed and has been deleted.</P>
</cfoutput>
</cfif>
<cfelse>
<!--- If no, post message or do some other function. --->
<cfoutput><p>The directory did NOT exist.</p></cfoutput>
</cfif>
<!---EXAMPLE 3: List directories
The following example creates both an array of directory names and a query that contains entries for the directories only. --->
<cfdirectory directory="C:/temp" name="dirQuery" action="LIST">
<!--- Get an array of directory names. --->
<cfset dirsArray=arraynew(1)>
<cfset i=1>
<cfloop query="dirQuery">
<cfif dirQuery.type IS "dir">
<cfset dirsArray[i]=dirQuery.name>
<cfset i = i + 1>
</cfif>
</cfloop>
<cfdump var="#dirsArray#">
<br>
<!--- Get all directory information in a query of queries.--->
<cfquery dbtype="query" name="dirsOnly">
SELECT * FROM dirQuery
WHERE TYPE='Dir'
</cfquery>
<cfdump var="#dirsOnly#">
|