User Guide Cancel

cffileupload

Last updated on May 30, 2024 | Also applies to ColdFusion

ColdFusion

Open app

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

Note:

cffileupload's Flash component has been deprecated. For more information, see the list of Deprecated features.

Description

Displays a dialog for uploading multiple files from the user's system. The enhanced dialog includes the following features:

You can specify the maximum number of files and the maximum file size for the upload.
A progress bar to visually indicate the overall progress of the file upload task, and another progress bar to indicate the upload progress of each individual file.
A success or failure message appears for each file upload and the overall upload task.
At any point during the upload task, you can cancel the upload.

Syntax

<cffileupload>  
addbuttonlabel= "label"  
align = "center|left|right"  
bgcolor = "color"  
clearbuttonlabel = "label"  
deletebuttonlabel = "label"  
extensionfilter = "none|jpg,jpeg,png"  
height= "number of pixels"  
hideUploadButton = "true|false"  
maxfileselect = "number of files"  
maxuploadsize = "file size in mega bytes"  
name = "File uploader name"  
oncomplete = "JavaScript function name"  
onerror = "JavaScript function name"  
onUploadComplete = "JavaScript function name"  
progressbar = "true|false"  
stoponerror = "true|false"  
style = "style specification"  
title = "Title panel name"  
uploadbuttonlabel = "label"  
url = "URL"  
width = "number of pixels"  
wmode = "window|opaque|transparent"  
</cffileupload>

cfscript equivalent of the syntax

<cfscript> 
    cffileupload(addbuttonlabel= "label" , align = "center|left|right" , bgcolor = "color" , clearbuttonlabel = "label" , deletebuttonlabel = "label" , extensionfilter = "none|jpg,jpeg,png"  
height= "number of pixels" , hideUploadButton = "true|false" , maxfileselect = "number of files" , maxuploadsize = "file size in mega bytes" , name = "File uploader name" , oncomplete = "JavaScript function name" , onerror = "JavaScript function name" , onUploadComplete = "JavaScript function name" , progressbar = "true|false" , stoponerror = "true|false" , style = "style specification" , title = "Title panel name" , uploadbuttonlabel = "label" , url = "URL" , width = "number of pixels" , wmode = "window|opaque|transparent" ) 
</cfscript>

Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

History

ColdFusion 9: Added this tag.

Attributes

Attribute	Req/Opt	Default	Description
addbuttonlabel	Optional	Add Files	Label of the Add button.
align	Optional	left	Specifies the default alignment. The following values are valid: center left right
bgcolor	Optional		The background color for the file upload control. A hexadecimal value without "#" prefixed or a recognized color name, for example red.
clearbuttonlabel	Optional	Clear All	Label of the Clear button
deletebuttonlabel	Optional	Delete	Label of the Delete button
extensionfilter	Optional	none	Use this attribute to specify the type of file that you will allow to be uploaded. For example, to let only image files to be uploaded, you can specify file extensions such as .jpg, .jpeg, or .png. If set to none, files are uploaded without any extension filter.
height	Optional	300	Height of the file upload control, in pixels.
hideUploadButton	Optional	false	A Boolean value that specifies if the Upload button should appear in the file upload dialog: true false
maxfileselect	Optional		The maximum number of files allowed for upload.
maxuploadsize	Optional	10MB	The maximum file size, in Megabytes, allowed for upload in an operation.ColdFusion throws an error if the value of the attribute maxuploadsize exceeds the throttle/ post data size settings specified in the ColdFusion Administrator.
name	Optional		Name of the file upload component.
onComplete	Optional		The JavaScript function to run when a file has finished uploading.By default, ColdFusion passes a JavaScript object as a parameter to this function with the following properties: STATUS - numeric value that is based on the HTTP status code MESSAGE - Passed or Failed FILENAME - Name of the file selected for upload You can also pass the JavaScript object by creating a struct with parameters "status" and "message" and call serializeJSON() on the JavaScript object.
onError	Optional		The JavaScript function to run if the uploading of a file fails. The error can be a network error or server-side error. By default, ColdFusion passes a JavaScript object as a parameter to this function with the following properties: STATUS - numeric value that is based on the HTTP status code MESSAGE - Passed or Failed FILENAME - Name of the file selected for upload You can also pass the JavaScript object by creating a struct with parameters "status" and "message" and call serializeJSON() on the JavaScript object.
onUploadComplete	Optional		The JavaScript function to run after uploading all the files.
progressbar	Optional	true	Whether to display a progress bar while the files upload: true false
stoponerror	Optional	true	Specifies whether to ignore the exceptions for this operation. true - Stops uploading and displays an appropriate error. false - Continues uploading and displays an appropriate error.
style	Optional		A CSS style specification that defines layout styles.
title	Optional		Title for the upload dialog.
uploadbuttonlabel	Optional	Upload	Label of the Upload button.
url	Optional		The URL to the server where the files are uploaded. The attribute is optional and it defaults to cgi.script_name.
width	Optional	420	Width of the file upload control, in pixels.
wmode	Optional	window	Specifies the absolute positioning and layering capabilities in your browser: window: Plays the media player in its own rectangular window on a web page opaque: Hides everything behind the media player on the web page transparent: Lets the background of the web page show through the transparent portions of the media player

Usage

Use this tag to create a SWF file-based file upload control that lets a user upload multiple files to a server. To upload files to the server, define a server-side template. The template that you define reads the upload request and uploads the selected files to the server.

Enhancements made in ColdFusion 9.0.1

In ColdFusion 9.0.1, the fileupload control passes the session information implicitly to the target page if session management is turned on either in Application.cfc or Application.cfm.Assume that fileupload control is defined without a URL attribute. In this case, if the user chooses to upload data using the upload button, the control comes back to the same page. Users can check for form.fieldnames to perform the upload as shown in the following example:Upload.cfm

<cfif isdefined("form.FIELDNAMES")> 
<cffile action = "upload" destination = "#ExpandPath('.')#" nameconflict="makeunique"> 
</cfif> 
<cffileupload name="myuploader">

In this case, url defaults to CGI.script_name.

To maintain sessions between the fileupload control and the URL, users must turn on session management. You can do this by setting the this.sessionmanagement=true in Application.cfc. The setting ensures that CFID and CFtoken are passed as part of the URL if Enable J2EE Session Variables (ColdFusion Administrator > Server Settings > Memory Variables) is not selected. If it is selected, then JsessionID is passed as part of the URL.

Supported Styles

The following are the supported styles:

Style	Description
headercolors	Format: color; colors of the band at the top of the DateChooser control. Specify two values, separated by a comma. For a solid band, use the same color for both values. The default value is ##E6EEEE,##FFFFFF.
textcolor	Color of text. Can be a hexadecimal value or a named color. For a hexadecimal value, use the form"##xxxxxx", where x = 0-9 or A-F; use two number signs or none.
titletextalign	Aligns the title text. The recognized values are left, right, and center. The default value is right.
titletextcolor	Color of the title text.
bgcolor	The background color for the file upload control. A hexadecimal value without "#" prefixed or a recognized color name, for example red.
rollovercolor	Displays values on mouse-over.
selectcolor	Background color for a selected item. Can be a hexadecimal value or a named color. For a hexadecimal value, use the form "##xxxxxx", where x = 0-9 or A-F; use two number signs or none. For a list of the supported named colors, see cfchart.

Example

<h3>Instructions</h3> 
<p>Create a folder Upload in your C: drive 
<br>Try uploading files using the file upload component and check if the files have been appropriately saved in the Upload folder.</p> 
<script> 
var foo = function(result) 
{ 
alert(ColdFusion.JSON.encode(result)); 
} 
</script> 
<cffileupload 
url="uploadFiles.cfm" 
progressbar="true" 
name="myupload" 
addButtonLabel = "Add File" 
clearButtonlabel = "Clear it" 
hideUploadButton = "true" 
width=600 
height=400 
title = "File Upload" 
maxuploadsize="30" 
extensionfilter="*.jpg, *.png, *.flv, *.txt" 
BGCOLOR="##FFFFFF" 
MAXFILESELECT=10 
UPLOADBUTTONLABEL="Upload now"/>

uploadfiles.cfm is given below:

<cffile action="upload" destination="#expandpath('./upload')#" nameconflict="makeunique"> <cfoutput>#serializeJSON({STATUS=200,MESSAGE='Passed'})#</cfoutput>

This example sends user-specified files to the server-side template - uploadfiles.cfm. The template file that you define can use the "upload" or "uploadall" action defined in the cffile tag.

Note: The filefield attribute of the upload action is optional.

Use the destination attribute in the cffile tag to define the location to save the files. For the uploadfiles.cfm code, see cffile action = "uploadAll".

Get help faster and easier

New user?