swfupload指南

SWFUpload

SWFUpload最初是由Vinterwebb.se开发的一个客户端的上传工具. 它结合了FLASH和JavaScript的功能，以提供一种超越了传统的浏览器中<input type="file" />标签提供的文件上传功能。

SWFUpload提供的主要特性:

在文件选择对话框中能够选择多个文件，即可以同时上传多个文件
类似AJAX的页面无刷新上传
提供上传进度的事件回调，实时显示上传进度
采用命名空间类以兼容其它JS库(如jQuery、Prototype等等)
对FLASH 9和FLASH 10播放器的支持(V2.2.0版本废弃了对Flash 8的支持)

SWFUpload不同于其他基于Flash构建的上传工具，它有着优雅的代码设计，开发者可以利用XHTML、CSS和 JavaScript来随心所欲的定制它在浏览器下的外观；它还提供了一组简明的JavaScript事件，借助它们开发者可以方便的在文件上传过程中更新页面内容来营造各种动态效果。

遗憾的是，为了能够触发文件浏览对话窗口，Flash Player 10迫使我们不得不在Flash影片中放入一个按钮。SWFUpload仍然允许用户通过JavaScript脚本来覆盖文本。

SWFUpload v2

SWFUpload v2包含了许多新的高级特性来改善稳定性，并提供一套有用的插件来解决FlashPlayer中的存在的bug。新特性包括：

兼容了Flash Player 10的安全机制
在文件上传的同时能够发送额外的POST数据
针对每一个文件上传发送POST/GET数据
一整套的事件回调机制
动态修改实例设置
接收服务端返回的数据
非取消形式的停止文件上传
自定义上传的顺序
支持单文件、多文件的文件的选择
可定制文件队列大小，文件上传数量和文件大小的限制
适当处理0字节的文件
支持预上传验证事件
解决(Work-arounds)Flash和浏览器中的bugs

概述

HTML上传

标准的HTML上传input表单字段为用户提供一个文本框和按钮来选择文件，选择的文件是通过form表单提交的。整个文件必须在下一个页面显示之前，完成上传，这种方式不能对选择的文件做预先的文件校验(如文件大小或有效的扩展名校验)，且当文件上传时，用户获得的可用的反馈信息很少。

传统的HTML上传模式十分简单,几乎所有浏览器都支持它。

SWFUpload

SWFUpload使用Flash影片来处理文件的选择和上传，由其中的定制Button来激活高级文件选择对话框。此文件选择对话框通过配置可以允许用户选择一个单独的文件或者是多个文件。 选择的文件类型可以通过配置来进行限制，以使用户只能选择指定的适当的文件，例如*.jgp;*.gif。

一旦选定了文件，所有的文件都会经过验证和入列。当上传文件的时候，由开发人员预定义的Javascript事件会被触发以便来更新页面中的UI，并实时提供提供上传状态和错误信息。

上传文件的提交和它页面的其它部分、表单是独立的。每个文件都是单独上传的，这就保证了服务端脚本能够更容易地处理单个文件。虽然Flash提供了上传服务，但是页面没有必要提交或者重新载入。相比于标准的HTML Form，SWFUpload的使用方式更像是AJAX程序，页面中的Form将会脱离于文件上传而进行单独处理。

入门

SWFUpload并不是拖放式的上传控件，它需要JavaScript和DOM的知识。一些可用的演示展示了它能够完成什么事情以及它是如何完成这些常见的任务。

SWFUpload由4部分组成：

1.初始化和设置(Javascript)
2.JavaScript 库: SWFUpload.js
3.Flash控制元素: swfupload.swf
4.事件处理器(JavaScript)

使用SWFUpload遇到的多数问题是由不正确地设置或者定义了糟糕的处理事件, Flash/Browser Bugs, 或服务端配置而引起的。

初始化和设置

SWFpload必须在页面中初始化，一般可以在window.onload事件中完成此操作。它的构造函数需要一个Object类型的设置对象。 这个设置对象一般是一个直接定义的Object类型变量，直接传递给SWFUpload的构造函数。

初始化的SWFUpload对象的引用需要保留下来，因为当显示文件选择对话框和启动文件上传的时候需要这个实例的引用。

示例:用直接定义的Object类型变量设置初始化SWFUpload对象

var swfu;

window.onload = function () {
swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_size_limit : "20 MB"
});
};

示例: 用存储在变量中的设置对象来初始化SWFUpload

var swfu;

window.onload = function () {
var settings_object = {
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_size_limit : "20 MB"
};

swfu = new SWFUpload(settings_object);
};

JavaScript 库

该JavaScript库文件(swfupload.js)应该包含在用户需要上传功能的页面中。

一旦SWFUpload创建完成，开发人员就可以用其专有的函数来控制此实例。

示例: 添加SWFUpload.js到页面中

<script type="text/javascript" src="http://www.swfupload.org/swfupload.js"></script>

示例: 使用其必须的设置来初始化SWFUpload

var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload_f9.swf",
button_placeholder_id : "spanSWFUploadButton"
});

Flash 控制元素

SWFUpload JavaScript 库可以动态加载Flash控制元素 (swfupload.swf).

Flash控制元素的文件位置必须在初始化的时候在SWFUpload设置对象中定义。

Flash控制元素是一个很小的用于处理文件浏览，验证和上传的Flash影片。它在页面中，它展现为一个按钮，并通过与Javascript通信来通知浏览器上传状态和其它事件。

The Event Handlers

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. Developers should not overwrite functions stored in SWFUpload.prototype. Instead create your own set of functions and pass references to them in the settings object.

事件处理

开发人员必须定义一系列JavaScript函数来处理SWFUpload事件回调，这些函数会在不同的重要事件发生时得到调用。

通过处理SWFUpload的事件，开发人员能够提供关于上传进度、出错信息以及上传完成等的信息反馈。开发人员不应该覆盖存储在SWFUpload.prototype中的函数，相反地，应该创建你自己的一系列函数并在设置对象中将引用传递给它们。

例如: swfupload事件处理和初始化

// uploadStart 事件处理器.该函数变量在设置对象中指定给了upload_start_handler属性。

var myCustomUploadStartEventHandler = function (file) {
var continue_with_upload;

if (file.name === "the sky is blue") {
continue_with_upload = true;
} else {
continue_with_upload = false;
}

return continue_with_upload;
};

//uploadSuccess处理事件。该函数变量在设置对象中指定给了upload_success_handler属性。
var myCustomUploadSuccessEventHandler = function (file, server_data, receivedResponse) {
alert("The file " + file.name + " has been delivered to the server. The server responded with " + server_data);
};

//创建SWFUpload实例，设置事件回调函数
var swfu = new SWFUpload({
upload_url : "http://www.swfupload.org/upload.php",
flash_url : "http://www.swfupload.org/swfupload.swf",
file_size_limit : "200 MB",

upload_start_handler : myCustomUploadStartEventHandler,
upload_success_handler : myCustomUploadSuccessEventHandler
});

SWFUpload JavaScript 对象

构造函数

SWFUpload(settings object)

返回: 一个SWFUpload实例

var swfupload_instance = new SWFUpload(settings_object);

全局变量和常量

特有的全局变量和常量是与SWFUpload对象相关的，它们对SWFUpload的高级应用程序和处理错误都是很有用的，它们都是只读的.

SWFUpload.instances

SWFUpload.instances 是一个对象，其中包含了页面中加载的每个SWFUpload的实例的引用。Flash Player 依赖此对象来调用正确的事件处理器. SWFUpload.instances是通过movieName属性来进行索引的.

SWFUpload.movieCount

SWFUpload.movieCount是一个全局变量，用于追踪已经创建的SWFUpload实例个数，并帮助确认每一个Flash影片分配了一个惟一的movieName。

SWFUpload.QUEUE_ERROR

SWFUpload.QUEUE_ERROR 是一个包含了错误码的简单JS对象，一般用来判断在fileQueueError事件发出的错误码，以确定fileQueueError的具体类型.

1.QUEUE_LIMIT_EXCEEDED - 用于指示用户试图入列超过设置允许的文件数量。一旦队列中的文件被更新和删除，则允许用户入列其它的文件。

2.FILE_EXCEEDS_SIZE_LIMIT - 用于指示选择的文件大小超过了由file_size_limit设置的值

3.ZERO_BYTE_FILE - 用于指示选择的文件为空.Flash Player 不会处理空文件.窗口快捷文件也会引发这个错误.

4.INVALID_FILETYPE - 选择的文件的扩展名与file_types设置的值不相匹配。用户可以手动输入一个文件名来绕开file_types的限制。

SWFUpload.UPLOAD_ERROR

1.SWFUpload.UPLOAD_ERROR 是一个包含上传错误码常量的简单对象。它通常用来判断在uploadError事件中发出的错误码类型。

2.HTTP_ERROR - 文件上传试图执行，但服务端没有返回200状态码。

3.MISSING_UPLOAD_URL - 没有设置upload_url.

4.IO_ERROR - 读或传输文件过程中出现的某种错误.这种错误通常是由于服务端出现未料到地连接中断所引起的.

5.SECURITY_ERROR - 上传违反了安全限制。这种错误很少出现。

6.UPLOAD_LIMIT_EXCEEDED - 用户试图上传的文件数超过了file_upload_limit设置的值.

7.UPLOAD_FAILED - 上传失败。这种错误一般很少见。

8.SPECIFIED_FILE_ID_NOT_FOUND - 文件ID传递给了startUpload，但file ID无法找到。

9.FILE_VALIDATION_FAILED - 文件验证失败，uploadStart事件返回false.

10.FILE_CANCELLED - cancelUpload被调用。

11.UPLOAD_STOPPED - stopUpload被调用。

SWFUpload.FILE_STATUS

SWFUpload.FILE_STATUS 是一个包含了文件状态码常量的简单对象。它可以用来检查File对象上文件状态属性。

1.QUEUED - 指示文件正等待入列。
2.IN_PROGRESS - 指示文件当前正在上传
3.ERROR -指示文件出现了队列或上传错误
4.COMPLETE - 指示文件已经成功上传到了服务器
5.CANCELLED - 指示文件由于调用了cancelUpload而取消了上传

SWFUpload.BUTTON_ACTION

SWFUpload.BUTTON_ACTION 是一个包含了button action代码常量的简单对象。它同button_action设置一起来设置基于文件对话框按钮Flash的行为。

1.SELECT_FILE - 当Flash button被点击的时候，文件对话框只允许选择一个文件。
2.SELECT_FILES - 当Flash button被点击的时候，文件对话框允许选择多个文件。
3.START_UPLOAD - 当Flash button被点击的时候，队列中的第一个文件将被上传。

SWFUpload.CURSOR

SWFUpload.CURSOR 是一个包含了按钮光标代码常量的简单对象。它与button_cursor设置一起使用来设置当鼠标光标停留于Flash button的行为.

1.ARROW - 光标将会显示为箭头指针。
2.HAND - 光标将会显示为手形指针。

SWFUpload.WINDOW_MODE

SWFUpload.WINDOW_MODE是一个包含了该SWF插入到页面中的wmode属性的JS对象.可以通过设置button_window_mode属性来告诉浏览器具体以哪种模式显示此SWF。


WINDOW是默认的模式. 该SWF将位于页面元素的最高层级。

OPAQUE　该SWF可以被页面类的其他元素通过层级的设置来覆盖它。

TRANSPARENT 该SWF的背景是透明的，可以透过它看到背后的页面元素。

属性

下面这个列表是相关属性的具体描述。使用其它属性或者对只读属性进行了写的操作都会造成SWFUpload出现问题。

customSettings (read/write)

customSettings属性是一个空的JavaScript对象，它被用来存储跟SWFUpload实例相关联的数据。它的内容可以使用设置对象中的custom_settings属性来初始化。

Example:

// 使用自定义的配置来初始化SWFUpload对象
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"; // 更改一个存在的自定义设置
swfu.customSettings.myNewCustomSetting = "new custom setting value"; // 添加一个新的自定义设置

//用一个全新的对象重写customSettings
swfu.customSettings = {
custom_setting_A : "custom_setting_value_A",
custom_setting_B : "custom_setting_value_B"
};

存储在customSettings对象中的值可以很轻松地在事件处理器中访问：

function uploadSuccess(file, serverData, receivedResponse) {
if (this.customSettings.custom_setting_A === true) {
alert("Checked the custom setting!");
}
}

movieName（只读）

包含了该SWFUpload实例的惟一影片名字。该值被传递给Flash，用来完成Flash和JavaScript的通信。该值被用来索引实例在SWFUpload.instances数组中的位置，你无法更改此值。

Methods

下面的方法用来操作SWFUpload。其中有些方法可以跟元素（例如，按钮）的点击事件绑定，其它的方法供SWFUpload内部处理事件中调用。

object addSetting(setting_name, value, default_value)

废弃. 此函数用来设置值。如果值为undefined，那么值为default_value设定的值。此函数是在SWFUpload初始化时被调用的。使用此函数来更新设置的值不会改变在Flash控制元素中设定的值。

此函数将返回存储在设置中的值。

object getSetting(setting_name)

废弃。此函数用来获取addSetting中设置的值。如果没有找到，将返回空字符串。

object retrieveSetting(setting_value, default_value)

v2.1.0已经删除此函数。此函数的功能除了不能修改内部的设置的值外，其它功能与addSetting相似。retrieveSetting返回设置的值(未定义时返回default_value)

bool destroy()

v2.1.0中新增

用于将一个SWFUpload实例从页面中销毁。不但删除DOM中的Flash元素，同时还删除SWFUpload实例的相关引用。同时它也会阻止在IE中的内存泄露。如果删除成功返回true，失败返回false。

void displayDebugInfo()

调用debug方法，在Debug输出框中显示SWFUpload实例的设置信息，如果设置中的debug属性是true，那么默认是在实例化完成以后自动调用此方法。

void selectFile()

废弃.不兼容Flash Player 10.

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.

void selectFiles()

Deprecated. Not compatible with Flash Player 10.

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.

void startUpload(file_id)

startUpload causes the file specified by the file_id parameter 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.

void cancelUpload(file_id, trigger_error_event)

cancelUpload cancels the file specified by the file_id parameter. The file is then removed from the queue.

If the file_id parameter is omitted or undefined then the first file in the queue is cancelled.

The trigger_error_event is optional. If set to false the uploadError event is suppressed.

void stopUpload()

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.

object getStats()

Retrieves the stats object.

void setStats(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.

object getFile(file_id|index)

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

void addPostParam(name, value)

The addPostParam function adds a name/value pair that will be sent in the POST for all files uploaded.

The name/value pair will also appear in the post_params setting.

void removePostParam(name)

The removePostParam function removes a name/value pair from the values sent with the POST for file uploads.

The name/value pair is also be removed from the post_params setting.

bool addFileParam(file_id, name, value)

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.

bool removeFileParam(file_id, name)

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.

void setUploadURL(url)

Dynamically modifies the upload_url setting.

void setPostParams(param_object)

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.

void setFileTypes(types, description)

Dynamically updates the file_types and file_types_description settings. Both parameters are required.

void setFileSizeLimit(file_size_limit)

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

void setFileUploadLimit(file_upload_limit)

Dynamically modifies the file_upload_limit setting. The special value zero (0) indicates "no limit".

void setFileQueueLimit(file_queue_limit)

Dynamically modifies the file_queue_limit setting. The special value zero (0) indicates "no limit".

void setFilePostName(file_post_name)

Dynamically modifies the file_post_name setting. The Linux Flash Player ignores this setting.

void setUseQueryString(use_query_string)

Dynamically modifies the use_query_string setting. When true this forces SWFUpload to send post parameters on the query string rather than in the post. The use_query_string parameter should be a boolean true or false.

void setDebugEnabled(debug_enabled)

Dynamically enables or disables debug output. The debug_enabled parameter should be a boolean true or false.

void setButtonImageURL(url)

Dynamically change the image used in the Flash Button. The image url must be relative to the swfupload.swf file, an absolute path (e.g., starting with a /), or a fully qualified url (e.g., http://www.swfupload.org/buttonImage.png). Any image format supported by Flash can be loaded. The most notable formats are jpg, gif, and png.

The button image is expected to be a button sprite (or a single image file with several images stacked together). The image will be used to represent all the button states by moving the image up or down to only display the needed portion. These states include: normal, hover, click, disabled. See the sample button images.

void setButtonDimensions(width, height)

Dynamically change the Flash button's width and height. The values should be numeric and should not include any units. The height value should be 1/4th of the total button image height so the button state sprite images can be displayed correctly

void setButtonText(text)

Sets the text that should be displayed over the Flash button. Text that is too large and overflows the button size will be clipped.

The text can be styled using HTML supported by the Flash Player (Adobe Documentation)

void setButtonTextStyle(css_style_text)

Sets the CSS styles used to style the Flash Button Text. CSS should be formatted according to the Flash Player documentation (Adobe Documentation)

Style classes defined here can then be referenced by HTML in the button_text setting.

void setButtonTextPadding(left, top)

Sets the top and left padding of the Flash button text. The values may be negative.

void setButtonDisabled(isDisabled)

When 'true' changes the Flash Button state to disabled and ignores any clicks.

void setButtonAction(buttonAction)

Sets the action taken when the Flash button is clicked. Valid action values are taken from the BUTTON_ACTION constants.

void setButtonCursor(buttonCursor)

Sets the mouse cursor shown when hovering over the Flash button. Valid cursor values are taken from the CURSOR constants.

Events

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.

SWFUpload events should be set only by assigning the event handler function in the settings object during object initialization. You should not override the internal functions belonging to the SWFUpload.prototype object.

During a file upload events are usually called in this order (the Upload Event Chain):

uploadStart
uploadProgress (called over and over again as the file uploads)
uploadError (called if some kind of error occurs, the file is canceled or stopped)
uploadSuccess (the upload finished successfully, data returned from the server is available)
uploadComplete (the upload is complete and SWFUpload is ready to start the next file)
flashReady()

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.

swfUploadLoaded()

The swfUploadLoaded event is fired by flashReady. It is settable. swfUploadLoaded is called to let you know that it is safe to call SWFUpload methods.

fileDialogStart()

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.

fileQueued(file object)

The fileQueued event is fired for each file that is queued after the File Selection Dialog window is closed.

fileQueueError(file object, error code, message)

The fileQueueError event is fired for each file that was not queued after the File Selection Dialog window is closed. A file may 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 a SWFUpload.QUEUE_ERROR constant.

fileDialogComplete(number of files selected, number of files queued, total number of files in the queued)

The fileDialogComplete event fires after the File Selection Dialog window has been closed and all the selected files have been processed. The 'number of files queued' argument indicates the number of files that were queued from the dialog selection (as opposed to the number of files in the queue).

If you want file uploading to begin automatically this is a good place to call 'this.startUpload()'

uploadStart(file object)

uploadStart is called immediately before the file is uploaded. This event provides an opportunity 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.

uploadProgress(file object, bytes complete, total bytes)

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.

uploadError(file object, error code, message)

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(file object, server data, received response)

uploadSuccess is fired when the entire upload has been transmitted and the server returns a HTTP 200 status code. Any data outputted by the server is available in the server data parameter.

Due to some bugs in the Flash Player the server response may not be acknowledged and no uploadSuccess event is fired by Flash. In this case the assume_success_timeout setting is checked to see if enough time has passed to fire uploadSuccess anyway. In this case the received response parameter will be false.

The http_success setting allows uploadSuccess to be fired for HTTP status codes other than 200. In this case no server data is available from the Flash Player.

At this point the upload is not yet complete. Another upload cannot be started from uploadSuccess.

uploadComplete(file object)

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 when calling uploadStart inside the uploadComplete event if you also have code that cancels all the uploads in a queue.

debug(message)

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).

SWFUpload Utility Objects

Settings object

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",
flash_url : "http://www.swfupload.org/swfupload.swf",

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"
},
use_query_string : false,
requeue_on_error : false,
http_success : [201, 202],
assume_success_timeout : 0,
file_types : "*.jpg;*.gif",
file_types_description: "Web Image Files",
file_size_limit : "1024",
file_upload_limit : 10,
file_queue_limit : 2,

debug : false,

prevent_swf_caching : false,
preserve_relative_urls : false,

button_placeholder_id : "element_id",
button_image_url : "http://www.swfupload.org/button_sprite.png",
button_width : 61,
button_height : 22,
button_text : "<b>Click</b> <span class="redText">here</span>",
button_text_style : ".redText { color: #FF0000; }",
button_text_left_padding : 3,
button_text_top_padding : 2,
button_action : SWFUpload.BUTTON_ACTION.SELECT_FILES,
button_disabled : false,
button_cursor : SWFUpload.CURSOR.HAND,
button_window_mode : SWFUpload.WINDOW_MODE.TRANSPARENT,

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",
}
}
Settings Description

upload_url

The upload_url setting accepts a full, absolute, or relative target URL for the uploaded file. Relative URLs should be relative to document. The upload_url should be in the same domain as the Flash Control for best compatibility.

If the preserve_relative_urls setting is false SWFUpload will convert the relative URL to an absolute URL to avoid the URL being interpreted differently by the Flash Player on different platforms. If you disable SWFUploads conversion of the URL relative URLs should be relative to the swfupload.swf file.

file_post_name

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.

post_params

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 object. Values must be either strings or numbers (as interpreted by the JavaScript typeof function).

Note: Flash Player 8 does not support sending additional post parameters. SWFUpload will automatically send the post_params as part of the query string.

use_query_string

The use_query_string setting may be true or false. This value indicates whether SWFUpload should send the post_params and file params on the query string or the post. This setting was introduced in SWFUpload v2.1.0.

preserve_relative_urls

A boolean value that indicates whether SWFUpload should attempt to convert relative URLs used by the Flash Player to absolute URLs. If set to true SWFUpload will not modify any URLs. The default value is false.

requeue_on_error

The requeue_on_error setting may be true or false. When this setting is true any files that has an uploadError (excluding fileQueue errors and the FILE_CANCELLED uploadError) is returned to the front of the queue rather than being discarded. The file can be uploaded again if needed. To remove the file from the queue the cancelUpload method must be called.

All the events associated with a failed upload are still called and so the requeuing the failed upload can conflict with the Queue Plugin (or custom code that uploads the entire queue). Code that automatically uploads the next file in the queue will upload the failed file over and over again if care is not taken to allow the failing upload to be cancelled.

This setting was introduced in SWFUpload v2.1.0.

http_success

An array that defines the HTTP Status Codes that will trigger success. 200 is always a success. Also, only the 200 status code provides the serverData.

When returning and accepting an HTTP Status Code other than 200 it is not necessary for the server to return content.

assume_success_timeout

The number of seconds SWFUpload should wait for Flash to detect the server's response after the file has finished uploading. This setting allows you to work around the Flash Player bugs where long running server side scripts causes Flash to ignore the server response or the Mac Flash Player bug that ignores server responses with no content.

Testing has shown that Flash will ignore server responses that take longer than 30 seconds after the last uploadProgress event.

A timeout of zero (0) seconds disables this feature and is the default value. SWFUpload will wait indefinitely for the Flash Player to trigger the uploadSuccess event.

file_types

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.

file_types_description

A text description that is displayed to the user in the File Browser dialog.

file_size_limit

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 interpreted as unlimited.

Note: This setting only applies to the user's browser. It does not affect any settings or limits on the web server.

file_upload_limit

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 interpreted 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.

file_queue_limit

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 remaining uploads allowed) is less than the queue limit then the lower number is used.

flash_url

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.

flash_width

(Removed in v2.1.0) 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.

flash_height

(Removed in v2.1.0) 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.

flash_color

Removed in v2.2.0 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.

prevent_swf_caching

Added in v2.2.0 This boolean setting indicates whether a random value should be added to the Flash URL in an attempt to prevent the browser from caching the SWF movie. This works around a bug in some IE-engine based browsers.

Note: The algorithm for adding the random number to the URL is dumb and cannot handle URLs that already have some parameters.

debug

A boolean value that defines whether the debug event handler should be fired.

button_placeholder_id

(Added in v2.2.0) This required setting sets the ID of DOM element that will be replaced by the Flash Button. This setting overrides the button_placeholder setting. The Flash button can be styled using the CSS class 'swfupload'.

button_placeholder

(Added in v2.2.0) This required setting sets the DOM element that will be replaced by the Flash Button. This setting is only applied if the button_placeholder_id is not set. The Flash button can be styled using the CSS class 'swfupload'.

button_image_url

(Added in v2.2.0) Fully qualified, absolute or relative URL to the image file to be used as the Flash button. Any Flash supported image file format can be used (another SWF file or gif, jpg, or png).

This URL is affected by the preserve_relative_urls setting and should follow the same rules as the upload_url setting.

The button image is treated as a sprite. There are 4 button states that must be represented by the button image. Each button state image should be stacked above the other in this order: normal, hover, down/click, disabled.

button_width

(Added in v2.2.0) A number defining the width of the Flash button.

button_height

(Added in v2.2.0) A number defining the height of the Flash button. This value should be 1/4th of the height or the button image.

button_text

(Added in v2.2.0) Plain or HTML text that is displayed over the Flash button. HTML text can be further styled using CSS classes and the button_text_style setting. See Adobe's Flash documentation for details.

button_text_style

(Added in v2.2.0) CSS style string that defines how the button_text is displayed. See Adobe's Flash documentation for details.

button_text_top_padding

(Added in v2.2.0) Used to vertically position the Flash button text. Negative values may be used.

button_text_left_padding

(Added in v2.2.0) Used to horizontally position the Flash button text. Negative values may be used.

button_action

(Added in v2.2.0) Defines the action taken when the Flash button is clicked. Valid action values can be found in the swfupload.js file under the BUTTON_ACTION object.

button_disabled

(Added in v2.2.0) A boolean value that sets whether the Flash button is in the disabled state. When in the disabled state the button will not execute any actions.

button_cursor

(Added in v2.2.0) Used to define what type of mouse cursor is displayed when hovering over the Flash button.

button_window_mode

(Added in v2.2.0) Sets the WMODE property of the Flash Movie. Valid values are available in the SWFUpload.WINDOW_MODE constants.

custom_settings

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";
Event Handlers

The remaining settings define the event handlers called by SWFUpload during its operation. JavaScript functions should be defined to handle these events as needed.

File Object

The file object is passed to several event handlers. It contains information about the file. Some operating systems do not fill in all the values (this is especially true for the createdate and modificationdate values).

{
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.

}
Stats Object

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
}
All these values can be updated using setStats() except the in_progress and files_queued values.

SWFUpload Plug-ins

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 plugins is contained in the plugin JavaScript file.

SWFObject

The SWFObject plugin uses the SWFObject library to handle the embedding of the SWFUpload Flash Component into the page.

This plugin also provides support for Document Ready loading and Flash Version Detection. Usage details are documented in the plugin file itself. You should not use the SWFObject's Document Ready loading mixed with another libraries DOMReady. Use one or the other but not both.

Flash Player 10: Because Flash Player 10 requires the SWFUpload swf to act is a button the movie must be visible in order for it to load. If the button_placeholder_id is set to an element that is hidden (visibility set to hidden or display set to none) SWFUpload will fail to load.

Cookies

In response to the Flash Cookie Bug the Cookies Plugin automatically retrieves your browser's cookies and sends them with the upload. The are sent as POST or GET variables to the upload url.

Note that this plugin sends the cookies name/values in the POST or GET. On the server side they will not be accessible as cookies. Some frameworks that automatically check cookies for session or authentication values still will not be able to find the values.

Queue Handling

This plugin provides Queue Handling features such as entire queue uploading, entire queue cancelling and automatic starting of uploads after being queued.

Speed

This Plugin extends the 'file' object with several properties that describe the current upload. This includes current speed, average speed, elapsed time, remaining time and more.

Known Issues

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 but there are some things that we cannot fix.

Cancelling in Linux

Older Flash 9 Players for Linux cause the browser to crash if an upload is cancelled. Newer Flash 9 Players behave better.

Upload Progress in Linux

The Flash Player in Linux sends a single uploadProgress event after the file has finished uploading.

In some distributions the entire browser locks up while the upload is in progress.

Upload Progress in OS X

There have been some reports that uploadProgress events are not fired in MAC Flash Players. The specifics haven't been pinned down but be aware of the possible issue.

MIME Type

The Flash Player uploads all files with a mime type of application/octet-stream regardless of the file's actual mime type.

Maximum number of selected files

The Flash Player does not impose a maximum number of selected files. However, it builds a selected files string which does have a maximum length. The string is built using the file's name and the separator [space]. The total number of files selected is determined by the sum of the lengths of the file names and a prefixed and postfixed  character (2 characters) and the number of files selected minus one times 3 (for the separator string)

This limitation may vary from system to system. If a use selects too many files they will be receive a Flash Player generated warning message and will be left at the File Selection Dialog.

Proxies

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 until it reaches 100% and will then seem to pause until the proxy completes uploading the file to the server.

Apache mod_security

Apache's mod_security validates POST to the server. Flash Player has implemented an edge case (there is argument as to whether it is invalid or note) POST for file uploads and so servers implementing mod_security will reject the upload. mod_security can be disabled using your .htaccess file

SSL

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. There especially seems to be an issue with using self-signed certificates.

Also, SSL tickets from untrusted Certificate Authorities (CA) do not work as Flash does not provide a method for accepting the certificate. It has been noted that, like the cookie bug, that Flash Player on Windows obtains its trusted CA list from Internet Explorer regardless of the browser in use.

Authentication

HTTP Authentication is not well supported by the Flash Player. Later versions of Flash Player behave better. Old version of Flash Player would crash the browser.

Prematurely terminated connections

Prematurely ending the response (such as a Response.end() in ASP.Net) can sometimes cause successful uploads to be reported as failed.

Filedata in Linux

Changing the Filedata value (file_post_name setting) is ignored in Linux Flash Players.

Cookie issue

On Windows the Non-IE Flash Player plugin (FireFox, Opera, Safari, etc) will send the IE cookies regardless of the browser used. This breaks authentication and sessions for many server-side scripting technologies.

Developers should manually pass Session and Authentication cookie information and manually restore Sessions on the Server Side if they wish to use Sessions

The SWFUpload package contains work-around sample code for PHP and ASP.Net

ExternalInterface bugs

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.

Server Data length bugs

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.

Avant Browser

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.

SWFUpload v2.2.0 added the prevent_swf_caching setting that attempts to work around this issue.

File Dialog & Page Changing

Leaving or reloading the current page while the File Browser Dialog window is open will cause the browser to crash (all browsers, all OSs). Most commonly this is caused by failing to cancel a click event on an <a> tag where the onclick event calls the selectFile or selectFiles function.

Long Running Upload Scripts

After Flash has uploaded the file to the webserver the upload script is executed. This script handles the file whether that means saving it, creating a thumbnail, scanning for viruses, etc. If the upload script does not return any data within 30 seconds Flash will disconnect and return an IO Error. You can prevent this by returning characters or data while the script runs (if possible). For PHP, the script continues to run and complete successfully even though Flash has terminated the connection. Any data returned by the script after Flash has disconnected is lost.

WMODE / BUTTON_WINDOW_MODE

In some browsers the selected WMODE (which is set using the BUTTON_WINDOW_MODE) can prevent the Flash Control from loading if the control is not on screen. The control will finally load once the user scrolls the page so the control becomes visible.

This behavior can adversely affect the SWFObject plugin. No SWFUpload events will be fire and the button image will not be loaded until the control becomes visible.

Memory Leaks

Some browsers (especially IE) cannot recover memory used by the Flash Player when JavaScript communication via the ExternalInterface classes is used (like in SWFUpload). Creating many SWFUpload instances and/or reloading the page several times will cause the browser to consume more and more memory until it crashes or otherwise harms the system.

In v2.2.0 SWFUpload we gave implemented some preventative measures. Some of these measures are pro-active but it is still recommended that you call the destroy method when the page unloads. If you are using hundreds of SWFUpload instances on a page you should use caution and test carefully for memory leaks.

Other Mac Issues

Users have reported that uploading to subdomains does not work with the Mac Flash Player.
Users have reported that pages that redirect (HTTP Status 302) are not handled by the Mac Flash Player. Windows clients seem to handle this issue.
The flash documentation states that on OS early than OS X 10.3 the bytes loaded is always reported as -1. SWFUpload converts this to 0 but the total bytes will never be sent and 100% won't be reached. The UI should be updated to display 100% complete in uploadSuccess or uploadComplete events to maintain a consistent UI.
Some users have reported issues if there is a space character in the upload_url for the Mac Flash Player. Avoid spaces or try replacing them with + or %20.
Users have reported that the Flash Player for Mac adds the PORT to the HTTP_HOST server variable (e.g., http://www.example.com:80). If you are checking this variable in your server-side script be aware of the possible issue.