Using the cffile Tag

Using the <cffile> Tag

The <cffile> tag allows you to do the following:

• Upload text or binary files from a Web browser.

• Read, write, and append to ASCII-based text files.

• Move, copy, or delete files on the Web server.

The various tasks that the <cffile> tag enables you to perform can be specified in its action attribute. For example, to write to a file on the Web server, specify write as the value of the action attribute. The other required attributes depend on the value of the action attribute.

The action attribute accepts nine valid values:

• Upload. Used to transfer a file from a client Web browser to a physical directory on the Web server.

• Move. Used to move a specified file stored on a specified directory on the Web server to a different directory.

• Rename. Used to change the name of a specified file on the Web server.

• Copy. Used to copy a file in a specified directory to another directory on the Web server.

• Delete. Used to delete a specified file on the Web server.

• Read. Used to read the contents of a specified text file in a variable that can be used in a ColdFusion page.

• ReadBinary. Used to read the contents of a specified binary file, such as an image or an executable application in a variable that can be used in a ColdFusion page.

• Write. Used to write to a specified text file on the Web server.

• Append. Used to add text to a specified text file on the Web server.

Understanding the action Attribute of the <cffile> Tag

As mentioned, the action attribute of the <cffile> tag is used to specify the kind of action to be taken on a file in the Web server. To use the <cffile> tag to upload a file from the client side to the server, you need to specify upload as the value of the action attribute.

The syntax of the <cffile> tag for uploading a file from the client side to the server is as follows:

 <cffile   action = "upload"   fileField = "Name_of_File_Form_field"   destination = "destination_path_"   accept = "mime_type/file_type"   nameConflict = "behavior"   attributes = "list_of_file_attributes"> 

The different attributes of the <cffile> tag for specifying an upload are

• action. Used to specify the kind of file operation to perform.

• fileField. Used to specify the name of the file field on an HTML upload form that's used for selecting a file to be uploaded to the server. Creating an HTML upload form is discussed in the section "Uploading Files" later in this chapter.

• destination. Used to specify the absolute physical path of the file or directory. For example, if you specify c:\testupload\myfile.doc as the value of the destination attribute, the uploaded file is stored as c:\testupload\myfile.doc on the server.

• nameConflict. Used to avoid any filename conflict with an existing file on a specified directory. When you upload a file from the client side to the server, it's possible that a file with the same filename already exists on the server. This leads to an error. To avoid this error, you can set MakeUnique as the value of the nameConflict attribute. Then, if ColdFusion finds a file with the same name in the destination directory, it forms a unique name for the file to be uploaded. Alternately, you can set the nameConflict attribute to Overwrite. In this case, when a file is uploaded to the server, ColdFusion replaces the file with the same name on the server with the uploaded file.

• Accept. Used for restricting uploads of files of a specific Multipurpose Internet Mail Extensions (MIME) type. The accept attribute is used to make sure that a file of a specific type is uploaded to the server. For example, if you want to allow only Microsoft Word document files to be uploaded to the server, you can set the value of the accept attribute to application/msword.

• attributes. Used for setting the file attributes, such as readonly, to be set for the uploaded file.

The following code uses the <cffile> tag to upload a file to the c:\uploads directory on the Web server:

 <cffile action = "upload"   fileField = "FileContents"   destination = "C:\uploads\" > 

Once a file is uploaded to the server, you can use various other upload attributes to determine its status. These upload attributes are invoked in a ColdFusion page using the cffile prefix. Some of these upload attributes are listed in Table 11.1.

Table 11.1: File Upload Attributes

Attribute	Function
ClientDirectory	Retrieves the directory on the client computer from which the file is uploaded.
ClientFile	Retrieves the name of the file on the client computer.
ServerDirectory	Retrieves the directory of the server computer where the file is uploaded.
ServerFile	Retrieves the filename of the file that's uploaded to the server.
FileSize	Retrieves the size of the uploaded file.
ContentType	Retrieves the MIME type of the uploaded file.
FileExisted	Determines whether a file with the same name already exists in the server directory.
FileWasOverwritten	Determines whether the uploaded file overwrote an existing file.
TimeCreated	Retrieves the time when the file was uploaded to the server.

Note

The various upload attributes that are used to determine the status of the uploaded file are always used after the <cffile> tag is called in a ColdFusion page.

The following code uses the serverFile and serverDirectory attributes to display the name and location of the file uploaded to the server:

 <HTML> <HEAD> </HEAD> <BODY> <cffile action = "upload"   fileField = "FileContents"   destination = "C:\uploads\" > The file named #cffile.serverFile# was uploaded to the following directory #cffile.serverDirectory# </BODY> </HTML> 

Uploading Files

To upload a file to the server, you have to create two ColdFusion pages:

• HTML upload form page. This contains the file form field used to specify the file to be uploaded to the server.

• Action page. This contains the <cffile> tag used to upload and store the file in a specified destination directory on the server.

Creating the HTML Upload Form Page

The HTML upload form used to specify file upload is different from a simple HTML form that's used to send plain-text content to a server-side program on the Web server. The syntax for the <form> tag for the HTML form used for uploading a file on the server is as follows:

 <form            action="action_page"            method="post"            enctype="multipart/form-data" > 

This HTML <form> tag contains the following attributes:

• action. Specifies the name of the ColdFusion page that processes the upload form

• method. Specifies the HTTP method by which the form contents are transferred to the server

• enctype. Specifies the type of content being transferred from the HTML form to the server

To create the HTML upload form page, create a ColdFusion page using the following code:

 <HTML> <head> <title>The Upload Form</title> </head> <body> <h2>Specify the File to Be Uploaded</h2> <form action="fileupload.cfm"      enctype="multipart/form-data"      method="post"> <table>    <tr><td colspan=2> Click the Browse button to specify the file to be uploaded. </td></tr> <tr> <td>File Location</td> <td>   <input type="file"        name="Upload_file"        size="30">   </td> <tr> <td colspan=2 align=center>   <input    type="submit"        value="Upload"> </td> </tr> </table> </form> </body> </HTML> 

Save the ColdFusion page as a .cfm file, such as uploadform.cfm, in the wwwroot directory under the ColdFusion MX server root directory.

Creating the ColdFusion Action Page for Uploading the File

The ColdFusion action page that's used to upload a file contains the <cffile> tag. The action attribute of the <cffile> tag is set to specify that <cffile> is being used for uploading a file on the server.

To create the ColdFusion action page, use the following code:

 <html> <head> <title>Upload File</title> </head> <body> <h2>Upload File</h2> <cffile action="upload"      destination="D:\CfusionMx\wwwroot\uploads"      nameConflict="overwrite"      fileField="Form.Upload_file" > <cfoutput> You have uploaded the#cffile.ClientFileName#.#cffile.ClientFileExt#        file to #cffile.ServerDirectory#. </cfoutput> </body> </html> 

Save the ColdFusion page as a .cfm file, such as fileupload.cfm, and store it in the wwwroot directory under the ColdFusion root directory.

Viewing the Upload Form and Performing the Upload

To upload a file to the server, perform the following steps:

1. View the HTML upload form in the Web browser by typing the URL of the upload form page. For example, type http://<computer_name>:8500/uploadform.cfm.

   In the preceding URL, <computer_name> is the computer name or host name of the computer where ColdFusion MX is installed.

   The HTML upload form is shown in Figure 11.1.

   
   Figure 11.1: The HTML upload form.

2. Select a file on the local computer by clicking the Browse button. This launches the Choose file dialog box, as shown in Figure 11.2.

   
   Figure 11.2: Selecting a file on the local computer.

3. Click the Upload button in the HTML form to transfer the file to the Web server. The Web server then runs the ColdFusion action page mentioned in the action attribute of the HTML form. The ColdFusion action page then receives and uploads the file to a location specified in the <cffile> tag, as shown in Figure 11.3.

   
   Figure 11.3: Uploading a file.