Uploader has been rebuilt in version 3.5.0, and a number of additional supporting modules (`UploaderFlash`, `UploaderHTML5`, `Uploader.Queue` and `File`) have been added. The new architecture is not fully backward-compatible with versions 3.4.1 and prior. This guide is to help answer questions that may come up when upgrading to the latest version.

This guide focuses on 3.4.1 API compatibility. It does not describe new features added in 3.5.0. Refer to the updated Uploader user guide for that.

If you are unable to upgrade due to unresolvable issues, you can use the `uploader-deprecated` module, which is equivalent to the 3.4.1 implementation. But be aware that this module will be removed in a future version of YUI.

Overview of API changes from 3.4.1

The architectural changes resulted in the deprecation, replacement, or removal of some of the attributes, properties, methods and events from 3.4.1 version of the Uploader. Here is a quick list of the changes most likely to affect your upgrade:

Attribute changes

Attribute in 3.4.1 Change in 3.5.0
`buttonSkin` No longer exists. The Uploader in Flash mode is now always rendered as transparent, overlaying a "Select Files" button that can be replaced with any control (with any skin) using the `selectFilesButton` attribute.
`fileFilters` Only available when the Uploader is in Flash mode, and has no effect when the Uploader is in HTML5 mode. If filtering by extension is needed across all Uploader modes, it is best to implement it post-selection, by validating individual elements in the `fileList`.
`log` No longer exists. All necessary uploader information is transmitted via events.
`multiFiles` Renamed to `multipleFiles`
`transparent` No longer exists. The Uploader in Flash mode is now always rendered as a transparent overlay over a "Select Files" button that can be customized or replaced with any control using the `selectFilesButton` attribute.

Method changes

Method in 3.4.1 Change in 3.5.0
`cancel` No longer exists on the Uploader instance. Instead, a `cancelUpload()` method is present on the instance of Uploader's queue, stored in `uploaderInstance.queue`. (See the API Docs for more information).
`clearFileList` No longer exists. Instead, you can directly manipulate the `fileList` attribute.
`enable` No longer exists. Instead, set the `enabled` attribute to either `true` or `false`.
`disable` No longer exists. Instead, set the `enabled` attribute to either `true` or `false`.
`removeFile` No longer exists. Instead, you can directly manipulate the `fileList` attribute.
`upload` The method signature has changed. The new `upload()` method takes `file`, `url`, and `postVars` as arguments, where `file` is a references to an instance of `Y.File` (can be obtained from the `fileList` attribute), `url` is the target URL to upload the file to, and `postVars` is a set of key-value pairs specifying the variables that should be POSTed along with the file upload. The old `method` argument has been removed since file upload requests are always POSTed. The old `postFileVarName` argument has been replaced with an instance-level `fileFieldName` attribute. (See the API Docs for more information).
`uploadAll` The method signature has changed. The new `uploadAll()` method takes `url`, and `postVars` as arguments, where `url` is the target URL to upload the files to, and `postVars` is a set of key-value pairs specifying the variables that should be POSTed along with the file upload. If POST variables need to be specified per file, you can use the `postVarsPerFile` attribute instead of specifying the third argument. The old `method` argument has been removed since file upload requests are always POSTed. The old `postFileVarName` argument has been replaced with an instance-level `fileFieldName` attribute. (See the API Docs for more information).
`uploadThese` The method signature has changed. The new `uploadThese()` method takes `files`, `url`, and `postVars` as arguments, where `files` is an array of `Y.File` instances (can be obtained as a subset of `fileList` attribute), `url` is the target URL to upload the files to, and `postVars` is a set of key-value pairs specifying the variables that should be POSTed along with the file upload. If POST variables need to be specified per file, you can use the `postVarsPerFile` attribute instead of specifying the third argument. The old `method` argument has been removed since file upload requests are always POSTed. The old `postFileVarName` argument has been replaced with an instance-level `fileFieldName` attribute. (See the API Docs for more information).

Improved Progressive Enhancement

The progressive enhancement scenario has been improved in 3.5.0 Uploader. The Uploader now keeps a static `TYPE` property (`Y.Uploader.TYPE`), which you can check before creating an instance of Uploader or modifying its configuration settings. We recommend the following pattern for using Uploader on your pages: ``` if (Y.Uploader.TYPE != "none") { var uploaderInstance = new Y.Uploader(....); // Common configuration settings. if (Y.Uploader.TYPE == "html5") { // Additional configuration settings for an HTML5 uploader, // e.g. a drag-and-drop area specification, etc. } else if (Y.Uploader.TYPE == "flash") { // Flash-specific configuration settings, // e.g. a fileFilters setting, etc. } // Render the uploader uploaderInstance.render("#selectFilesButtonContainer"); } else { // Don't render the uploader and use predefined basic functionality // instead (e.g. a simple upload form field). } ```

Backend Setup

The backend requirements for the Flash version of the Uploader have not changed. However, the XMLHttpRequest Level 2 cross-domain request security model is different from that in Flash, and needs a different type of verification from the backend that receives POST requests with uploaded files. See the Backend Setup section in the User Guide for more information, or read more about it on the HTML5Rocks website.

What Did We Miss?

Obviously, there were quite a few changes to Uploader from 3.4.1 to 3.5.0. It's likely that we missed something here. If you experience trouble with your upgrade and find this migration guide is missing something important, please file a ticket and we'll update it as soon as possible.

Additional resources to help with the upgrade include the forums, and the #yui IRC channel on freenode.net.