SWFUpload is a client-side file upload tool originally developed by Vinterwebb.se. It uses a combination of Flash and JavaScript to provide file upload functionality beyond what the basic browser provides with the <input type="file" /> tag.
The main features that SWFUpload provides are:
SWFUpload is different from other Flash based upload tools because of the philosophy behind its design. SWFUpload gives developers control by leaving the UI in the browser. Developers can use XHTML, CSS, and JavaScript to tailor the upload UI to the needs and style of their site. Upload status updates are made through a set of simple JavaScript events. The developer uses these events to update the webpage as the file upload progresses.
SWFUpload v2 includes new advanced features, improved stability, Flash Player bug work-arounds and a helpful set of Plug-ins. New features include:
SWFUpload v2 continues the SWFUpload design goal of leaving the UI in the hands of developers and extends it even further.
The standard HTML upload input box provides a box and a button to the user for selecting a file. The file is submitted with the form. The entire file must be uploaded before the next page is displayed. No pre-upload validation can be made on the file (e.g., file size limits or valid extensions). Very little feedback is given to the user while the file uploads.
The usage pattern for standard HTML uploads is simple, straight forward, and supported by nearly all browser.
SWFUpoad uses a hidden Flash movie to handle file selection and upload. JavaScript is used to activate the file selection dialog. The file selection dialog is configured to allow the user select to a single file or to multiple files. The file types can be restricted so users only select the appropriate files (e.g., *.jpg;*.gif).
Once files are selected each is processed and validated. As the file is processed and upload by Flash JavaScript events are fired which the developer overrides in order to update the page UI. Providing upload status and error messages in real-time.
The uploaded file is submitted separately from the rest of the page and form. Each file is uploaded individually which keeps the server-side upload handling script simple as it only has to handle a single uploaded file at a time. Since Flash is providing the upload service the page does not have to be submitted or reloaded. The usage pattern for SWFUpload is more like that of an AJAX application than that of a standard HTML form. The page's form will be processed separately from the file upload.
SWFUpload is not a drag & drop upload control. It requires knowledge of JavaScript and the DOM. Several demos are available that show what some things SWFUpload is capable of and how to accomplish common tasks.
SWFUpload consists of 4 pieces:
Most problems implementing SWFUpload are caused by incorrect settings or poorly built event handlers.
SWFUpload must be initialized on the page. This is commonly done in the window.onload event. The SWFUpload constructor requires a settings object. The settings object is often passed directly to the constructor as an object literal.
A reference to the initialized SWFUpload object should be kept as it is needed to display the File Selection Dialog and to start uploads.
Example: Initializing SWFUpload with an object literal
var swfu;
window.onload = function () {
swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
file_size_limit : "20480"
});
};
Example: Initializing SWFUpload with a settings object stored in a variable
var swfu;
window.onload = function () {
var settings_object = {
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
file_size_limit : "20480"
};
swfu = new SWFUpload(settings_object);
};
The JavaScript library file (swfupload.js) should be included on the page where the user will interact and upload pages. It is compatible with both Flash Player 8 and Flash Player 9 SWFUpload versions.
Once a SWFUpload object has been created access to several functions become available which allow the developer to control SWFUpload.
Example: Adding SWFUpload.js to a page
<script type="text/javascript" src="http://www.swfupload.org/swfupload.js"></script>
Example: Initializing SWFUpload with the required settings and binding selectFiles to a button.
var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf"
});
document.getElementById("BrowseButton").onclick = function () { swfu.selectFiles(); };
The SWFUpload JavaScript library dynamically loads the Flash Control (swfupload_f8.swf/swfupload_f9.swf). The Flash Control comes in two versions. One version supports Flash Player 8 and greater. It provides greater compatibility while sacrificing some features. The other supports Flash Player 9.0.28 and greater. It provides additional features while sacrificing compatibility with Flash Player 8 users.
The location of the Flash Control file must be provide in the SWFUpload settings object during setup.
The Flash Control is an invisible Flash Movie that handles file browsing, validation and upload. It does not provide any User Interface components but communications with JavaScript to notify the browser when updates to the page need to be made.
Developers must create a set of JavaScript functions that handle SWFUpload events. These functions are called as different important events occur.
By handling the SWFUpload events developers can provide feedback regarding the upload progress, error messages, and upload completion.
Example: SWFUpload event handlers and initialization.
// The uploadStart event handler. This function variable is assigned to upload_start_handler in the settings object
var uploadStartEventHandler = function (file) {
var continue_with_upload = true;
return continue_with_upload;
};
// The uploadSuccess event handler. This function variable is assigned to upload_success_handler in the settings object
var uploadSuccessEventHandler = function (file, server_data) {
alert("The file " + file.name + " has been delivered to the server. The server responded with " + server_data);
};
// Create the SWFUpload Object
var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
file_size_limit : "20480",
upload_start_handler : uploadStartEventHandler,
upload_success_handler : uploadSuccessEventHandler
});
SWFUpload(settings object)
Returns: A SWFUpload instance
var swfupload_instance = new SWFUpload(settings_object);
Several globals and constants are associated with the SWFUpload object. These are useful for advanced SWFUpload applications and for handling errors. These are considered read-only.
SWFUpload.instances is an array containing a reference to each SWFUpload instance loaded on a page. The Flash Player relies on this array in order to call the correct event handlers. SWFUpload.instances is indexed by the movieName property.
Note: SWFUpload.instances is not a true JavaScript array. It is actually a simple object.
SWFUpoad.movieCount is a global that tracks the number on SWFUpload instances that have been created and helps to ensure each movie is given a unique movieName.
SWFUpload.QUEUE_ERROR is a simple object that contains Queue Error code constants. It is generally used to determine which error code was sent in the fileQueueError event.
SWFUpload.UPLOAD_ERROR is a simple object that contains Upload Error code constants. It is generally used to determine which error code was sent in the uploadError event.
SWFUpload.FILE_STATUS is a simple object that contains File Status code constants. It can be used to check the file status property on the File object.
The SWFUpload library provides a set of default event handlers. These are used by the library to ensure that something is available to call even when you do not define custom event handlers. They should not be over-written when defining custom event handlers. Custom event handlers should be defined separately and bound using the settings object.
The following list of properties are intended for your use as described below. Using other properties or writing to read-only properties can cause SWFUpload to malfunction.
The customSettings property is an empty JavaScript object that can be used to store data associated with an instance of SWFUpload. The customSettings' contents can be initialized using the custom_settings setting.
Note: Some plug-ins use the customSettings object for their internal operation. Use caution when over-writing the entire customSettings object.
Example:
// Initialize SWFUpload with some custom settings
var swfu = new SWFUpload({
custom_settings : {
custom_setting_1 : "custom_setting_value_1",
custom_setting_2 : "custom_setting_value_2",
custom_setting_n : "custom_setting_value_n",
}
});
swfu.customSettings.custom_setting_1 = "custom_setting_value_1"; // Change an existing custom setting
swfu.customSettings.myNewCustomSetting = "new custom setting value"; // Add a new custom setting
// Overwrite the customSettings with a completely new object
swfu.customSettings = {
custom_setting_A : "custom_setting_value_A",
custom_setting_B : "custom_setting_value_B"
};
Contains the SWFUpload instance unique movie name. This value is passed to Flash and is used to facilitate Flash to JavaScript communication. This value is used to index the instance in the SWFUpload.instances array.
The following methods are used to operate SWFUpload. Some are bound to element (e.g., buttons) click event handlers and others are used inside SWFUpload event handlers.
The addSetting function sets a setting value. If the value is undefined then the default_value is used. The function is used by SWFUpload during initialization. Using addSetting to update a setting will not change the setting in the Flash Control.
addSetting returns the value that was stored in the setting.
The getSetting function retieves the value of a setting. If the setting is not found an empty string is returned.
The retrieveSetting function is similar to the addSetting function except it does not modify the internal settings object. retrieveSetting returns the setting_value unless it is undefined in which case it returns the default_value
This is a utility function.
The displayDebugInfo outputs SWFUpload settings using the debug event. This function is automatically called after initilization if the debug setting is 'true'
selectFile causes the Flash Control to display a File Selection Dialog window. A single file may be selected from the Dialog window.
Calling selectFile begins the File Event Chain.
selectFiles causes the Flash Control to display a File Selection Dialog window. A multiple files may be selected from the Dialog window.
Calling selectFiles begins the File Event Chain.
startUpload causes the file specified by the file_id paramter to start the upload process. If the file_id parameter is omitted or undefined then the first file in the queue is uploaded.
Calling startUpload begins the Upload Event Chain.
cancelUpload cancels the file specified by the file_id parameter. The file is then removed from the queue.
If the file_id paramter is omitted or undefined then the first file in the queue is cancelled.
If the file cancelled is currently being uploaded then the uploadError event is fired.
stopUpload stops and re-queues the file currently being uploaded.
After the uploading file is stopped the uploadError event is fired. If no file is being uploaded then nothing happens and no event is fired.
Retrieves the stats object.
The Stats Object may be modified. This is useful if you wish to change the number of successful uploads or upload errors after an upload has completed.
getFile is used to retrieve a File Object from the queue. The file retrieved by passing in a file id (the id property from a file object) or a file index (the index property from a file object).
When getting a file by file_id only files in the queue are available. If the file is not found null is returned.
When getting a file by index all queued (or files that generated a queue error) are available. If the index is out of range then null is returned
The addFileParam function adds a name/value pair that will be sent in the POST with the file specified by the file_id parameter.
The name/value pair will only be sent with the file it is added to. To send name/value pairs with all uploads use the post_param setting.
The removeFileParam function removes a name/value pair from a file upload that was added using addFileParam.
If the name/value pair was not found then 'false' is returned.
Dynamically modifies the upload_url setting.
Dynamically modifies the post_params setting. Any previous values are over-written. The param_object should be a simple JavaScript object. All names and values must be strings.
Dynamically updates the file_types and file_types_description settings. Both parameters are required.
Dynamically modifies the file_size_limit setting. This applies to all future files that are queued. The file_size_limit parameter will accept a unit. Valid units are B, KB, MB, and GB. The default unit is KB.
Examples: 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB
Dynamically modifies the file_upload_limit setting. The special value zero (0) indicates "no limit".
Dynamically modifies the file_queue_limit setting. The special value zero (0) indicates "no limit".
Dynamically modifies the file_post_name setting. The Linux Flash Player ignores this setting.
Dynamically enables or disables debug output. The debug_enabled parameter should be a boolean true or false.
SWFUpload fires various events during its operation. These events can be handled by the developer to update the UI, change behavior, or report errors.
All SWFUpload events are called in the context of a SWFUpload instance. This means that the 'this' object refers to the SWFUpload instance that fired the event.
flashReady is an internal event that should not be overwritten. It is called by the Flash Control to notify SWFUpload that the Flash movie has loaded and is ready to accept commands.
The swfUploadLoaded event is fired by flashReady. It is overridable. When swfUploadLoaded is called it is safe to call SWFUpload methods.
fileDialogStart is fired after selectFile for selectFiles is called. This event is fired immediately before the File Selection Dialog window is displayed. However, the event may not execute until after the Dialog window is closed.
The fileQueued event is fired for each file that is queued after the File Selection Dialog window is closed.
The fileQueueError event is fired for each file that was not queued after the File Selection Dialog window is closed. A file may not not be queued for several reasons such as, the file exceeds the file size, the file is empty or a file or queue limit has been exceeded.
The reason for the queue error is specified by the error code parameter. The error code corresponds to SWFUpload.QUEUE_ERROR contant.
The fileDialogComplete event fires after the File Selection Dialog window has been closed and all the selected files have been processed.
If you want file uploading to begin automatically this is a good place to call 'this.startUpload()'
uploadStart is called immediately before the file is uploaded. This event provides an oppurtunity to perform any last minute validation, add post params or do any other work before the file is uploaded.
The upload can be cancelled by returning 'false' from uploadStart. If you return 'true' or do not return any value then the upload proceeds. Returning 'false' will cause an uploadError event to fired.
The uploadProgress event is fired periodically by the Flash Control. This event is useful for providing UI updates on the page.
Note: The Linux Flash Player fires a single uploadProgress event after the entire file has been uploaded. This is a bug in the Linux Flash Player that we cannot work around.
The uploadError event is fired any time an upload is interrupted or does not complete successfully. The error code parameter indicates the type of error that occurred. The error code parameter specifies a constant in SWFUpload.UPLOAD_ERROR.
Stopping, Cancelling or returning 'false' from uploadStart will cause uploadError to fire. Upload error will not fire for files that are cancelled but still waiting in the queue.
uploadSuccess is fired when an upload completes and the server returns a HTTP 200 status code. Any data outputted by the server is available in the server data parameter (Flash Player 9 version only).
At this point the upload is not yet complete. Another upload cannot be started from uploadSuccess.
uploadComplete is always fired at the end of an upload cycle (after uploadError or uploadSuccess). At this point the upload is complete and another upload can be started.
If you want the next upload to start automatically this is a good place to call this.uploadStart(). Use caution calling uploadStart inside the uploadComplete event if you are trying to cancel all the uploads in a queue.
The debug event is called by the SWFUpload library and the Flash Control when the debug setting is set to 'true'. If the debug event is not overridden then SWFUpload writes debug messages to the SWFUpload console (a text box dynamically added to the end of the page body).
The settings object is a JavaScript object that provides the settings for the SWFUpload instance. Each setting should only appear once. Many settings are optional and provide suitable default values if omitted. See the setting details for required and optional settings.
Example:
{
upload_url : "http://www.swfupload.org/upload.php",
file_post_name : "Filedata",
post_params : {
"post_param_name_1" : "post_param_value_1",
"post_param_name_2" : "post_param_value_2",
"post_param_name_n" : "post_param_value_n"
},
file_types : "*.jpg;*.gif",
file_types_description: "Web Image Files",
file_size_limit : "1024",
file_upload_limit : 10,
file_queue_limit : 2,
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
flash_width : "1px",
flash_height : "1px",
flash_color : "#FFFFFF",
debug : false,
swfupload_loaded_handler : swfupload_loaded_function,
file_dialog_start_handler : file_dialog_start_function,
file_queued_handler : file_queued_function,
file_queue_error_handler : file_queue_error_function,
file_dialog_complete_handler : file_dialog_complete_function,
upload_start_handler : upload_start_function,
upload_progress_handler : upload_progress_function,
upload_error_handler : upload_error_function,
upload_success_handler : upload_success_function,
upload_complete_handler : upload_complete_function,
debug_handler : debug_function,
custom_settings : {
custom_setting_1 : "custom_setting_value_1",
custom_setting_2 : "custom_setting_value_2",
custom_setting_n : "custom_setting_value_n",
}
}
The upload_url setting accepts a full, absolute, or relative target URL for the uploaded file. Full or absolute URLs are recommended because some browsers/Flash Players use different base directories. The upload_url should be in the same domain as the Flash Control.
(Flash 9 only) The file_post_name allows you to set the value name used to post the file. This is not related to the file name. The default value is 'Filedata'. For maximum compatibility it is recommended that the default value is used.
The post_params setting defines the name/value pairs that will be posted with each uploaded file. This setting accepts a simple JavaScript object. Multiple post name/value pairs should be defined as demonstrated in the sample settings ojbect.
Note: Flash Player 8 does not support sending additional post parameters. SWFUpload will automatically send the post_params as part of the query string.
The file_types setting accepts a semi-colon separated list of file extensions that are allowed to be selected by the user. Use '*.*' to allow all file types.
A text description that is displayed to the user in the File Browser dialog.
The file_size_limit setting defines the maximum allowed size of a file to be uploaded. This setting accepts a value and unit. Valid units are B, KB, MB and GB. If the unit is omitted default is KB. A value of 0 (zero) is interpretted as unlimited.
Note: This setting only applies to the user's browser. It does not affect any settings or limits on the web server.
Defines the number of files allowed to be uploaded by SWFUpload. This setting also sets the upper bound of the file_queue_limit setting. Once the user has uploaded or queued the maximum number of files she will no longer be able to queue additional files. The value of 0 (zero) is interpretted as unlimited. Only successful uploads (uploads the trigger the uploadSuccess event) are counted toward the upload limit. The setStats function can be used to modify the number of successful uploads.
Note: This value is not tracked across pages and is reset when a page is refreshed. File quotas should be managed by the web server.
Defines the number of unprocessed files allowed to be simultaneously queued. Once a file is uploaded, errored, or cancelled a new files can be queued in its place until the queue limit has been reached. If the upload limit (or maining uploads allowed) is less than the queue limit then then lower number is used.
The full, absolute, or relative URL to the Flash Control swf file. This setting cannot be changed once the SWFUpload has been instantiated. Relative URLs are relative to the page URL.
Defines the width of the HTML element that contains the flash. Some browsers do not function correctly if this setting is less than 1 px. This setting is optional and has a default value of 1px.
Defines the height of the HTML element that contains the flash. Some browsers do not function correctly if this setting is less than 1 px. This setting is optional and has a default value of 1px.
This setting sets the background color of the HTML element that contains the flash. The default value is '#FFFFFF'.
Note: This setting may not be effective in "skinning" 1px flash element in all browsers.
A boolean value that defines whether the debug event handler should be fired.
The custom_settings setting allows developers to safely attach additional information to a SWFUpload instance without worrying about affecting internal SWFUpload values or changes in new SWFUpload versions. This setting accepts a JavaScript object.
Once instantiated the custom settings are accessed in the 'customSettings' property of the SWFUpload instance.
var swfu = new SWFUpload({
custom_settings : {
"My Setting" : "This is my setting",
myothersetting : "This is my other setting",
integer_setting : 100,
a_dom_setting : document.getElementById("some_element_id")
}
});
var my_setting = swfu.customSettings["My Setting"]);
swfu.customSettings["My Setting"] = "This is my new setting";
swfu.customSetting.myothersetting = "another new value";
swfu.customSetting.integer_setting += 25;
swfu.customSetting["a_dom_setting"].style.visibility = "hidden";
The remaining settings define the event handlers called by SWFUpload during its operation. JavaScript functions should be defined to handle these events as needed.
The file object is passed to several event handlers. It contains information about the file.
{
id : string, // SWFUpload file id, used for starting or cancelling and upload
index : number, // The index of this file for use in getFile(i)
name : string, // The file name. The path is not included.
size : number, // The file size in bytes
type : string, // The file type as reported by the client operating system
creationdate : Date, // The date the file was created
modificationdate : Date, // The date the file was last modified
filestatus : number, // The file's current status. Use SWFUpload.FILE_STATUS to interpret the value.
}
The Stats object provides information about the upload queue.
That stats object contains the following properties:
{
in_progress : number // 1 or 0 indicating if a file upload is currently in progress
files_queued : number // The number of files currently in the queue
successful_uploads : number // The number of files that have uploaded successfully (caused uploadSuccess to be fired)
upload_errors : number // The number of files that have had errors (excluding cancelled files)
upload_cancelled : number // The number of files that have been cancelled
queue_errors : number // The number of files that caused fileQueueError to be fired
}
With SWFUpload v2.0 several plugins have been introduced. They are provided to help with common tasks associated with implementing SWFUpload.
Currently most of the documentation for using the plugis is contained in the plugin JavaScript file.
This plugin provides additional settings and logic for automatically hiding and showing page elements based on whether SWFUpload loads.
This plugin provides some functions for loading SWFUpload as soon as possible, rather than waiting until window.onload fires. This is similar to Document Ready functionality found in JavaScript Libraries like Prototype and jQuery. It should not be mixed with other Document Ready libraries
Creates compatibility with v1.0.2. Using this plugin you should be able to drop SWFUpload v2.0 in to a v1.0.2 page
In response to the Flash Cookie Bug the Cookies Plugin automatically retrieves your browser's cookies and sends them with the uploads. The are sent as POST or GET variables to the upload url.
This plugin is yet to be developed
This plugin will implement Adobe's Flash Detection Kit for SWFUpload providing more advanced Flash Detection and upgrade features.
This plugin provides Queue Handling features such as entire queue uploading, entire queue cancelling and automatic starting of uploads after being queued.
The Flash Player and many Browsers have bugs that have a direct impact on the performance of SWFUpload. While we have worked hard to get around many issues there are some things we cannot fix.
Flash 8 and older Flash 9 Players for Linux cause the browser to crash if an upload is cancelled. Newer Flash 9 Players behave better.
The Flash Player in Linux sends a single uploadProgress event after the file has finished uploading.
The Flash Player may not properly use proxies. It does not handle authenticating proxies well (if at all) and will some-times crash.
Some anti-virus software uses a proxy to scan uploads and cause SWFUpload to believe the entire file has been uploaded. SWFUpload will fire uploadProgress events very quickly and will then wait until the proxy completes its upload.
Apache's mod_security validates POST to the server. Flash Player has implemented an invalid POST for file uploads and so servers implementing mod_security will reject the upload. mod_security can be disabled using your .htaccess file
There have been some reports that the Flash Player cannot upload through SSL. The issue has not been pinned down but uploading over SSL may be unreliable.
HTTP Authentication is not well supported by Flash Player. Later versions of Flash Player behave better. Old version of Flash Player would crash the browser.
Prematurely ending the response (such as a Response.end() in ASP.Net) can sometimes cause successful uploads to be reported as failed.
The Filedata value (file_post_name setting) is ignored in Linux Flash Player
The uploadSuccess will not fire if no data is returned from the server. This is especially problematic on the Mac Flash Player.
On Windows the Non-IE Flash Player plugin (FireFox, Opera, Safari, etc) sends the IE cookes regardless of the browser used. This breaks authentication and sessions for many server-side scripting technologies.
Developers should manually pass Session ID information and manually restore Sessions on the Server Side if they wish to use Sessions
Flash Player does not properly escape data when communication with the browser/JavaScript. SWFUpload goes to great lengths to work-around this issue. If this bug is fixed in future Flash Players/Browsers then SWFUpload will send extra escaped data.
Very long server data is corrupted on Mac and Linux Flash Players. Server data will be truncated, garbled, and/or repeated. We recommend keeping data returned from the server short and concise.
For some users the Avant Browser does not work with SWFUpload after the Flash Control has been cached. This has been reproduced by the SWFUpload developers but the Avant Browser developers did not experience any problems.
When the page is reloaded SWFUpload loads and fires the swfupload_loaded event. However, none of the ExternalInterface callback functions are defined on the movie element. SWFUpload v2.0.2 has added checks which prevent swfupload_loaded from firing if the callback functions are not detected.