Description
Manages interactions with server files. The following sections describe the actions of the cffile tag:
- cffile action = "append"
- cffile action = "copy"
- cffile action = "delete"
- cffile action = "move"
- cffile action = "read"
- cffile action = "readBinary"
- cffile action = "rename"
- cffile action = "upload"
- cffile action = "uploadAll"
-
Note: To execute, this tag must be enabled in the ColdFusion Administrator. For more information, see Configuring and Administering ColdFusion.
If your ColdFusion applications run on a server used by multiple customers, consider the security of the files that could be uploaded or manipulated by
cffile . For more information, see Configuring and Administering ColdFusion.
Category
Syntax
The tag syntax depends on the action attribute value. See the following sections.
See also
History
ColdFusion 10: Modifications to the attribute accept}}
ColdFusion 9: {{uploadAll action
ColdFusion 8: Support for reading and writing
ColdFusion MX 7:
- Added the result attribute, which allows you to specify an alternate variable in which to receive result parameters. Used for action = "upload" action.
- Added the fixnewline attribute for action = "append" and action = "write" actions.
ColdFusion MX 6.1: - Changed file path requirements: if you do not specify an absolute file path, the path is relative to the ColdFusion temporary directory, which is returned by the GetTempDirectory function.
- Changed behavior for action="read": if the file starts with a byte order mark (BOM) ColdFusion uses it to determine the character encoding.
- Changed behavior for action="upload" nameConflict="MakeUnique" ColdFusion now makes filenames unique by appending
a incrementing number, 1 for the first file, 2 for the second and so on, to the name. In ColdFusion, filenames were made unique by appending an additional "1" for each file, as in 1, 11, 111, and so on.
ColdFusion MX: - Changed use of slashes in paths: you can use forward or backward slashes in paths on both UNIX and Windows systems.
- Changed file hierarchy requirements: ColdFusion does not require that you put files and directories that you manipulate with this tag below the root of the web server document directory.
- Changed directory path requirements for the destination attribute: a directory path that you specify in the destination attribute does not require a trailing slash.
- Deprecated the system value of the attributes attribute.
- Deprecated the temporary value of the attributes attribute. In ColdFusion, it is a synonym for normal. It might not work in later releases.
- Changed the action attribute options read, write, append and move: they support a new attribute, charset.
- The archive value of the attributes attribute is obsolete and has no effect.
Provide file content in the tag body
For cffile action = "append" and cffile action = "write", you can provide file content in the tag body. If you provide file content in both the tag body and the output attribute, it results in an error. In the following example, the text provided in the body is written to myfile.txt in the current directory.Now assume that the file does not exist, then a new file myfile.txt is created. If the file exists, it is overwritten.
<cfset filename = expandpath('./myfile.txt')> |
Similarly, if you use cffile action="append", the tag body content is appended to the contents of the file myfile.txt. To create an empty file, you have to provide at least a blank line in the tag body as shown in the following code:
<!--- Leave a blank line here---> |
Modifications to the attribute accept in ColdFusion 10
The attribute accept takes comma-separated list of any or all extensions, MIME type, or list of MIME types as values. Specify the extensions with a . prefix. That is, only .txt is supported and not txt, *.txt, or *.*. However, you can use * as a wildcard to accept all files.
- If you specify filename extension as value, the file is checked, only to ensure if it matches the list of extensions you specified in
comma-separated list. If it matches, the file is uploaded. - If the value is MIME type or list of MIME types and the attribute strict is set to true, then the first few bytes of the file are read to determine the MIME type. If MIME type matches with what you have specified, upload occurs, else results in an error. The default value of strict is true.
- If you specify both filename extensions and MIME types and if strict is set to false, the verification is based on the order in which you have specified the values. For example, if the first value is .txt, then the .txt file is uploaded.
If strict is set to true, extensions are ignored.
Example: Using the attribute accept to verify the filename extension
upload.cfm
<cfset variables.URL = "http://#cgi.server_name#:#cgi.server_port## |
_upload.cfm
<!--- create upload directory ---> |
In this example, accept is set to .txt and strict is not specified (and therefore is true by default). So, only files with .txt extensions are considered for upload.Even if the file is originally a PDF (sample.pdf) renamed as sample.txt, the file is uploaded (since strict is not set to true).
If you specify strict=true, then if the file is originally a .txt (and not renamed from some other type) the file is uploaded only if the correct MIME type is specified. That is, strict=true requires MIME type to be specified in the
Example 2: Using MIME type
Modify the Example 1 by specifying accept="application/pdf" in _upload.cfm as follows:
destination="#uploadDirectory#" |
Since strict = true, only files of type PDF are considered for upload. To use a different file, modify the following section of upload.cfm:
<cfhttpparam type="FILE" name="myfile" file="#expandpath('./sample.txt')#"> |
Example 3: Using both extension and MIME type
Modify the Example 1 by specifying the following in _upload.cfm:
action="UPLOAD" |
Only PDF files are uploaded because strict = true. If you set strict as false, then both the files are uploaded.
To use a different file, modify the following snippet of upload.cfm:
<cfhttpparam type="FILE" name="myfile" file="#expandpath('./sample.txt')#"> |
Example
| This is a view-only example. ---> <!--- <cfif IsDefined("form.formsubmit") is "Yes"> <!--- The form has been submitted, now do the action. ---> <cfif form.action is "new"> <!--- Make a new file. ---> <cffile action="Write" file="#GetTempDirectory()#foobar.txt" output="#form.the_text#"> </cfif> <cfif form.action is "read"> <!--- Read existing file. ---> <cffile action="Read" file="#GetTempDirectory()#foobar.txt" variable="readText"> </cfif> <cfif form.action is "add"> <!--- Update existing file. ---> <cffile action="Append" file="#GetTempDirectory()#foobar.txt" output="#form.the_text#"> </cfif> <cfif form.action is "delete"> <!--- Delete existing fil. ---> <cffile action="Delete" file="#GetTempDirectory()#foobar.txt"> </cfif> </cfif> <!--- Set some variables. ---> <cfparam name="fileExists" default="no"> <cfparam name="readText" default=""> <!--- First, check whether canned file exists. ---> <cfif FileExists("#GetTempDirectory()#foobar.txt") is "Yes"> <cfset fileExists="yes"> </cfif> <!--- Now, make the form that runs the example. ---> <form action="index.cfm" method="POST"> <h4>Type in some text to include in your file:</h4> <p> <cfif fileExists is "yes"> <p>A file exists (foobar.txt, in <cfoutput>#GetTempDirectory()#</cfoutput>). You may add to it, read from it, or delete it. </p> </cfif> <!--- If reading from a form, let that information display in textarea. ---> <textarea name="the_text" cols="40" rows="5"> <cfif readText is not ""> <cfoutput>#readText#</cfoutput> </cfif></textarea> <!--- Select from the actions depending on whether the file exists. ---> <select name="action"> <cfif fileExists is "no"> <option value="new">Make new file </cfif> <cfif fileExists is "yes"> <option value="add">Add to existing file <option value="delete">Delete file <option value="read">Read existing file </cfif> </select> <input type="Hidden" name="formsubmit" value="yes"> <input type="Submit" name="" value="make my changes"> </form> ---> |
