Cold Fusion Markup Language CFFILE

CFFILE

Use the CFILE tag to handle all interactions with files. CFILE is more complicated than other CFML tags because the required attributes depend on the value of the ACTION attribute. For example, if the ACTION is "WRITE" Cold Fusion expects the attributes associated with writing a text file.

Note: Many CFFILE attributes apply to specific actions. Refer to the ACTION Attributes table in this section for details about which attributes can be used with which ACTIONs.

CFFILE ACTION Attributes

This table shows the attributes you can use with which CFFILE ACTIONs.

ACTION	Attributes	Description
APPEND	OUTPUT FILE	Evaluates the expression in APPEND and appends the result to the end of the file specified in the DESTINATION attribute.
COPY	SOURCE DESTINATION	Creates a copy of the file identified in SOURCE to the file path specified in DESTINATION.
DELETE	FILE	Deletes the file specified in the FILE attribute.
MOVE	SOURCE DESTINATION	Moves the file identified in SOURCE to the file path specified in DESTINATION.
READ	FILE VARIABLE	Reads the contents of a text file specified in the FILE attribute, and sets the variable named by VARIABLE.
RENAME	SOURCE DESTINATION	Moves the file identified in SOURCE to the file path specified in DESTINATION.
UPLOAD	ACCEPT DESTINATION FILEFIELD NAMECONFLICT	Uploads the file specified in FILEFIELD in the upload form and resolves any filename conflicts based on the value of NAMECONFLICT.
WRITE	OUTPUT FILE	Evaluates the expression in OUTPUT and writes the result to the file specified in FILE.

CFFILE ACTION="UPLOAD"

The CFFILE tag has the following attributes for the upload action:

CFFILE Tag ACTION="UPLOAD"
Attribute	Description
FILEFIELD	Required. The name of the form field which was used to select the file. Note: DO NOT USE # signs to specify the field name.
DESTINATION	Required. The destination directory on the Web server where the file should be saved. Note: the directory does not need to be beneath the root of the Web server document directory.
NAMECONFLICT	Optional. Default is error. Determines how the file should be handled if its name conflicts with the name of a file that already exists in the directory.
ACCEPT	Optional. Use to limit what types of files will be accepted (e.g. only image/jpeg files). Note: The browser uses the file extension to determine file type.

Resolving Conflicting File Names

Whenever a file is being saved to the server there is a risk that another file may already exist with the same name. In the event of this occurrence there are number of actions you can take using the NAMECONFLICT attribute.

The CFFILE NAMECONFLICT attribute can have any one of the following settings:

NAMECONFLICT	Description
ERROR	Default. The file will not be saved, and Cold Fusion will stop processing the template and return an error.
SKIP	Neither saves the file nor throws an error. This setting is intended to allow custom behavior based on inspection of FILE properties. See "Evaluating the Results of a File Upload" on page .
OVERWRITE	Replaces an existing file if it shares the same name as the CFFILE destination.
MAKEUNIQUE	Automatically generates a unique filename for the upload. This name will be stored in the FILE object variable "ServerFile." You can use this variable to record what name was used when the file was saved.

Example

The following example will create a unique file name if there is a name conflict when the file is upload:

<CFFILE ACTION="UPLOAD" 
   FILEFIELD="FileContents" 
   DESTINATION="C:\Web\Uploads\"
   NAMECONFLICT="MAKEUNIQUE">

Evaluating the Results of a File Upload

After a file upload is completed, there is a set of status information about the upload that you can use. The status information includes a wide range of data about the file upload including variables such as the fileÆs name and the directory where it was saved.

The status information about a file upload is available as a set of parameters. File upload status parameters (listed below) use the "File" prefix (i.e. "File.ClientPath"). The file status parameters can be used anywhere other Cold Fusion parameters can be used. For more information, refer to the Cold Fusion User Guide.

The following file upload status parameters are available after an upload:

Parameter	Description
ContentType	MIME content type of the saved file.
ContentSubType	MIME content subtype of the saved file.
ClientDirectory	Full path of the uploaded file on the clientÆs system.
ClientFile	Filename of the uploaded file on the clientÆs system.
ClientFileName	Filename without an extension of the uploaded file on the clientÆs system.
ClientFileExt	Extension of the uploaded file on the clientÆs system without a period.
ServerDirectory	Full path of the file actually saved.
ServerFile	Filename of the file actually saved.
AttemptedServerFile	Specifies whether or not Cold Fusion attempted to save a file. Indicates Yes or No.
FileExisted	Specifies whether or not the file already existed with the same path. Indicates Yes or No.
FileWasSaved	Specifies whether or not Cold Fusion saved a file. Indicates Yes or No.
FileWasOverwritten	Specifies whether or not Cold Fusion overwrote a file. Indicates Yes or No.
FileWasAppended	Specifies whether or not Cold Fusion appended a file to an existing file. Indicates Yes or No.
FileWasRenamed	Specifies whether or not the uploaded file was renamed to avoid a name conflict. Indicates Yes or No.

Tip: Use the File prefix to refer to these parameters (e.g. #File.FileExisted# ). Note: File status parameters are read-only. They are set to the results of the most recent CFFILE tag. (If two CFFILE tags execute, the results of the first tag are lost.)

CFFILE ACTION="MOVE"

The CFFILE tag can be used to move a file from one location on the server to another.

The CFFILE tag has the following attributes for the move action:

CFFILE Tag ACTION="MOVE"
Attribute	Description
SOURCE	Required. The file to move (with directory location).
DESTINATION	Required. The directory where the file will be moved to.

Example

The following example moves the file "KeyMemo.doc" file from the c:\files\upload\ directory to the c:\files\memo\ directory:

<CFFILE ACTION="MOVE"
   SOURCE="c:\files\upload\KeyMemo.doc"
   DESTINATION="c:\files\memo\">

CFFILE ACTION="RENAME"

The CFFILE tag can be used to rename a file that already exists on a server.

The CFFILE tag has the following attributes for the rename action:

CFFILE Tag ACTION="RENAME"
Attribute	Description
SOURCE	Required. The file to rename (with directory location).
DESTINATION	Required. The new name for the file (with directory location).

Example

The following example renames the file KeyMemo.doc to OldMemo.doc:

<CFFILE ACTION="MOVE"
   SOURCE="c:\files\memo\KeyMemo.doc"
   DESTINATION="c:\files\memo\OldMemo.doc">

CFFILE ACTION="COPY"

The CFFILE tag can be used to copy a file from one directory to another on the server.

The CFFILE tag has the following attributes for the copy action:

CFFILE Tag ACTION="COPY"
Attribute	Description
SOURCE	Required. The file to copy (with directory location).
DESTINATION	Required. The directory where the copy of the file will be saved.

Example

The following example saves a copy of the KeyMemo.doc file in the c:\files\backup\ directory:

<CFFILE ACTION="COPY"
   SOURCE="c:\files\upload\KeyMemo.doc"
   DESTINATION="c:\files\backup\">

CFFILE ACTION="DELETE"

The CFFILE tag can be used to delete a file on the server.

The CFFILE tag has the following attributes for the delete action:

CFFILE Tag ACTION="DELETE"
Attribute	Description
FILE	Required. The file to delete (with directory location).

Example

The following example permanently deletes the specified file:

<CFFILE ACTION="DELETE"
   FILE="c:\files\upload\#Variables.DeleteFileName#">

CFFILE ACTION="READ"

You can use the CFFILE tag to read an existing text file. The file is read into a dynamic parameter which you can use anywhere in the template file, like any other dynamic parameter. For example, you could read a text file and then insert its contents into a database. Or you could read a text file and then use one of the find and replace functions to modify the contents.

The CFFILE tag has the following attributes for the read action:

CFFILE Tag ACTION="READ"
Attribute	Description
FILE	Required. The text file to be read (with directory location).
VARIABLE	Required. The name of the variable that will contain the contents of the text file after it has been read.

Example

The following example will create a variable named "Message" which will contain the contents of the file "update.txt:"

<CFFILE ACTION="READ" 
   FILE="C:\Web\update.txt" 
   VARIABLE="Message">

The variable "Message" could then be used in the template. For example, you could display the contents of the message.txt file in the final Web page:

<CFOUTPUT>#File.Message#</CFOUTPUT>

Tip: Cold Fusion supports a number of powerful functions for manipulating the contents of text files. (See the string functions in the Cold Fusion Language Reference for more information about how to use these functions.)

CFFILE ACTION="WRITE"

You can use the CFFILE tag to write a text file based on dynamic content. For example, you could create static HTML files or log actions in a text file.

The CFFILE tag has the following attributes for the write action:

CFFILE Tag ACTION="WRITE"
Attribute	Description
FILE	Required. The name of the file to be created (with directory location).
OUTPUT	Required. The content of the file to be created.

Example

The following example creates a file with the information a user entered into an HTML insert form:

<CFFILE ACTION="WRITE" 
   FILE="C:\files\updates\#Form.UpdateTitle#.txt"
   OUTPUT="Created By: #Form.FullName#
   Date: #Form.Date# 
   #Form.Content# ">

If the user submitted a form with where:

UpdateTitle="FieldWork"
FullName="John Long"
Date="10/1/96"
Content="We had a wonderful time in Cambridgeport."

Cold Fusion would create a file named "FieldWork.txt" in the C:\files\updates\ directory. And the file would contain the text:

Created By: John Long
Date: 10/1/96
We had a wonderful time in Cambridgeport.

CFFILE ACTION="APPEND"

The CFFILE tag can be used to append additional text to the end of an existing text file, for example when creating log files.

The CFFILE tag has the following attributes for the append action:

CFFILE Tag ACTION="APPEND"
Attribute	Description
DESTINATION	Required. The file to which the content of the OUTPUT attribute will be appended (with directory location).
OUTPUT	Required. The string which will be appended to the file designated in the DESTINATION attribute.

Example

The following example will append the text string "But Davis Square was more fun." to the file FieldWork.txt which was created in the previous example:

<CFFILE ACTION="WRITE" 
   DESTINATION="C:\files\updates\FieldWork.txt"
   OUTPUT="<B>But Davis Square was more fun.</B>">