CFFILE As a ColdFusion developer who is thinking about interacting with the file system or working with files in general, you'll likely look to the CFFILE tag, and with good reason. The CFFILE tag is one of the most powerful tools you can use when you want to do just about anything to a file. Using the CFFILE tag, you can move, rename, copy, or delete files that exist on the server. You can read text files on the server into memory, append text to them, or create new ones altogether. In addition, CFFILE enables you to upload files from the client machine to your web server through simple Hypertext Markup Language (HTML) forms. In most cases, when you begin to look up reference information for a particular ColdFusion tag, you expect to see a table with the tag syntax and its common attributes. In the case of CFFILE, the attributes that are passed along with the CFFILE tag are dependent on the CFFILE action that you specify. The CFFILE tag can be used with any one of nine action types. Table 12.1 lists the various action types and common examples of their various uses. Table 12.1. CFFILE Tag Action Types | Action Type | Common Use | | append | Using the CFFILE append action type enables you to append text to the end of an existing text file. | | copy | Using the copy action type, you can copy any file from one location on the server to another, just like using the OS copy command. | | delete | The delete action type works just as the name implies, enabling you to delete a specific file from the server. | | move | The move action type moves a file from one server location to another. Unlike the COPY action type, in which, after copying, the file still exists in the original location, with the move action type, after the file is moved, it no longer exists in the first location. This is useful if you want to enable users to upload files to a temp directory, but then want those files copied to another location. Using the move action type in place of copy eliminates the need to go back and delete files from the temp directory. | | read | The read action type enables you to read the contents of a text file into memory. After it is in memory, you can use the variable as you would any other ColdFusion variable. | | readbinary | The readbinary action type works just like the READ action type, only that it enables you to read the contents of image files (or any other binary file). | | rename | Using the rename action type with CFFILE enables you to rename a specific file on the server. | | upload | The upload action type is used when you want web clients to be able to push a file up to your server. Used in conjunction with HTML forms, the upload action type saves the uploaded file to your web server. | | write | The write action type enables you to use ColdFusion to write out dynamic contents to a text file. | Understanding how each action type works and when to use each helps you determine which particular action is best suited for your development situation. For the purposes of the examples in this chapter, we'll use the UPLOAD action type because it's usually the one type developers want to make work first. For a full explanation of each action type and syntax, see Appendix A, "Tag Reference." Uploading Files to the Server When you want to use ColdFusion to enable your users to upload files to your web server, the first step is creating an HTML form in which they can specify the file that they want to upload. The following example demonstrates a simple upload form that enables users to submit a file to your server for upload. <html> <head> <title>File Upload Form</title> </head> <body> <h2>Choose File</h2> <form action="actionPage.cfm" enctype="multipart/form-data" method="post"> <p>Choose the file you would like to upload: <input type="file" name="File" size="30"> </p> <input type="submit" value"Upload"> </form> </body> </html> As you can see from this example, all we've done is create a simple form that enables users to choose which file they'd like to post to our server. The key when creating a file upload form is to make sure you use the correct enctype of "multipart/form-data" and to make sure that you use an input type of "file". This enables your HTML to be rendered with a Browse button that permits users to select a file on their local systems for upload. The output of the form creation code is shown in Figure 12.1. Figure 12.1. File upload form.  Now that we have our form built, we can focus on using CFFILE to upload the file to our server. In this case, because we want to upload the file, we'll want to use the CFFILE action type UPLOAD. The following section of code shows you how we need to build our actionPage.cfm file that enables the file to be uploaded to our server: <html> <head> <title>File Upload Action Page</title> </head> <body> <!---Begin the file upload---> <cffile action="upload" destination="#ExpandPath(".")#/" nameConflict="overwrite" fileField="Form.File"> <cfoutput> Upload of file: #cffile.serverfile# successful. </cfoutput> </body> </html> With this section of code, we are actually uploading to our server the file that the client selected. Because the file uploads to the server, its contents are written into the random-access memory (RAM) on our server. After the complete file is received, the contents of the file are pulled out of RAM and actually written to a file on disk. For this reason, it's important to make sure that you have sufficient RAM on your server if you intend to allow the uploading of large files. Otherwise, you'll see an out-of-memory error, telling you that you don't have enough system resources to complete the task. You might notice that in the output on our action page, we use some variables to tell us that the file was uploaded successfully. After a file upload is completed, you have several status variables available to you to help you determine that the upload was successful and to communicate informational messages to your users. FileExists Function You can use the FileExists() function to verify that a file was successfully uploaded to a server. The FileExists() function returns a simple "YES" value if the file you specify as an argument to the function is present on the server. The FileExists() function can be used in the following manner: <cfif FileExists(FullPathToYourFile)> The file you are looking for exists in the directory specified. </cfif> |
Table 12.2 gives you an overview of the status variables available to you after a completed file upload. It also gives their uses. Table 12.2. CFFILE Upload Status Variables | Status Variable | Use | | attemptedServerFile | This variable stores the name that ColdFusion first used when attempting to write the file to your server. If there was a name conflict when uploading the file to your server, the final filename might be different. | | clientDirectory | This variable tells you where the file came from on the client system. For example, if the user uploaded a file to your server from his or her C:\TEMP directory, that information would be present in this variable. | | clientFile | This variable stores the full name of the file being uploaded as it was on the client file system. | | clientFileName | This variable stores the name of the file as it was on the client file system, but without the file extension. | | clientFileExt | This variable stores only the file extension of the file being uploaded, as it was on the client file system. | | contentSubType | This variable stores the standard Multipurpose Internet Mail Extension (MIME) content subtype of the file being uploaded. For example, a value here might be GIF or JPEG. | | contentType | This variable stores the broader MIME content type of the file. Here, for example, you might see image listed as the MIME type. | | dateLastAccessed | This variable stores the date on which the file being uploaded was last accessed. | | fileExisted | This variable returns either yes or no, telling you whether a file of the same name or extension already exists in the location to which the current file is being uploaded. | | fileSize | This variable reports the size of the file being uploaded. This variable can be accessed only to get the total size of the file after the upload is complete. | | fileWasAppended | This variable returns either yes or no to let you know whether ColdFusion appended the uploaded file to the end of an existing file. | | fileWasOverwritten | This variable returns yes or no to let you know if a file on you server was overwritten to upload the current file. | | fileWasRenamed | This variable returns either yes or no to tell you whether ColdFusion had to rename the file being uploaded to avoid a name conflict. | | fileWasSaved | This variable simply tells you, yes or no, that the file was saved. | | oldFileSize | This variable reports the size of the file that was overwritten (if a file was indeed overwritten) during an upload operation. | | serverDirectory | This variable reports to you the directory on the server in which the uploaded file was saved. | | serverFile | This variable reports to you the name of the uploaded file after it's been saved on the server. This variable includes the complete filename, including the extension. | | serverFileName | This variable gives you the name of the file as it is stored on the server after upload, excluding the file extension. | | serverFileExt | This variable reports to you only the extension of the file that has been uploaded to the server. | | timeCreated | This variable reports to you the date and time that the uploaded file was created on the server. | | timeLastModified | This variable reports to you the date and time that the file was last modified. | You can use any of these output variables after an upload operation is complete to communicate status or to help manage the files on your server. |
