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

Category

System functions

Function Syntax

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

See Also

DirectoryCreateDirectoryDeleteDirectoryExistsDirectoryRename

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>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy