DirectoryList

Description

Lists the contents of on-disk or in-memory directory. Also lists the contents of the sub-directories if recurse is set to true.

Returns

Contents of the directory based on the parameter listInfo:

If listInfo="query", query object
If listInfo="name", array of names
If listInfo="path", array of path

Function Syntax

DirectoryList(path [,recurse] [,listInfo] [,filter] [,sort] [,type] )

History

ColdFusion 11: Added the type argument.

Parameters

Parameter

Description

path

The absolute path of the directory for which to list the contents. Alternatively, you can specify IP address as in the following example: DirectoryList("//12.3.123.123/c_drive/test");.

recurse

Whether ColdFusion performs the action on subdirectories: If true, contents of all subdirectories are also listed.

listInfo

name: returns an array of names of files and directories.
path: returns an array of paths of files and directories.
query: returns a query.

filter

File extension filter applied to returned names, for example, *.cfm. Multiple filters can be applied by using a pipe delimiter. For example: *.beer|*.cookies

Also, you can pass a function in the filter argument:

<cfscript>

boolean function filterBySize(path, type, extension) {
var sizeLimit = 1024 * 100; //more than 10 KB
var extensionList = "jpg,jpeg,gif,png";
if(type is "dir") return false;

if(listFindNoCase(extensionList,extension)) {
var fileInfo = getFileInfo(path);
var size = fileInfo.size;
if(size >= sizeLimit) return true;
}
return false;
}

filteredResults = directorylist(expandPath("."), true, "path", filterBySize);
writeDump(filteredResults);
</cfscript>

The arguments of the passed functions must have:

path: The file path
type: The values (file or dir )
extension: The file extension if any otherwise an empty string

Additionally, it can also accept the instances of Java FileFilter Objects.

sort

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:

asc: ascending (a to z) sort order.
dec: descending (z to a) sort order.
For example:sort = "directory ASC, size DESC, datelastmodified"

type

file: includes only filenames.
dir: includes only directory names.
all: includes both filenames and directory names.

Usage

Ensure that you have the required permissions to run this function.

Example

The following code dumps the contents of a directory:

<h2>DirectoryList Example</h2> 
<h3>Enter a directory for Listing.</h3> 
<cfform action = "directoryList.cfm" method="post" preservedata="true" > 
<label for="listDirectory">Directory Path: </label><cfinput type = "text" id="listDirectory" name = "listDirectory"> 
<br /> 
<label for="recurse">Recurse: </label><cfinput id="recurse" type="checkbox" value="recurse" name="recurse"> 
<br /> 
<label for="listInfo">List Info: </label> 
<cfselect name="listInfo" id="listInfo"> 
<option value="name">name</option> 
<option value="path">path</option> 
<option value="query">query</option> 
</cfselect> 
<br /> 
<label for="filter">Filter: </label><cfinput id="filter" type="text" value="" name="filter"> 
<br/> 
<input type = "submit" value="submit" name = "submit"> 
</cfform> 

<cfif IsDefined("FORM.listDirectory")> 
<cfif FORM.listDirectory is not ""> 
<cfset listDirectory = FORM.listDirectory> 
<cfset recurse = false> 
<cfif isDefined("FORM.recurse")> 
<cfset recurse = true> 
</cfif> 
<cfset listInfo = FORM.listInfo> 
<cfset filter = FORM.filter> 
<cftry> 
<cfset res= DirectoryList(listDirectory,recurse,listInfo,filter)> 
<cfoutput><b>Content of Directory #listDirectory#: </b></cfoutput> 
<cfdump var="#res#"> 
<cfcatch> 
<b>Error Message:</b><cfoutput>#cfcatch.message#</cfoutput><br/> 
<b>Error Detail:</b><cfoutput>#cfcatch.Detail#</cfoutput> 
</cfcatch> 
</cftry> 
</cfif> 
</cfif>

DirectoryList

Applies to

Description

Returns

Category

Function Syntax

See Also

History

Parameters

Usage

Example