migration.mustache revision 76438e9b6959cc0bd7e35fb9cf5a11c87a37f744
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major#docs-main li {
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major margin: 1ex 0;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major white-space: nowrap;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major background: #fcfbfa;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major border: 1px solid #d0d5ec;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major padding: 0 3px;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major border-color: #efeeed;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major.yui3-skin-sam table {
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major width: auto;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major.yui3-skin-sam td,
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major.yui3-skin-sam th {
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major border: 0 none;
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major.demo { width: 40%; }
dfc4e0fc3052835b2a069aa9d869fa1161c33fe6Peter Major.details { width: 60%; }
0e400e45fa5bef7103232d78fc7a54f7390e03d8Jonathan Scudder.before, .after { width: 47%; }
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major margin-left: 5%;
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major#quickref code em {
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major color: #900;
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major#quickref code strong {
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major color: #090;
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major margin-top: 0;
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major margin-bottom: 0;
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major color: #b00;
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major<div class="intro">
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major Uploader has been rebuilt in version 3.5.0, and a number of additional
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major supporting modules (`UploaderFlash`, `UploaderHTML5`, `Uploader.Queue`
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major and `File`) have been added. The new architecture is <strong>not fully
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major backward-compatible</strong> with versions 3.4.1 and prior. This guide
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major is to help answer questions that may come up when upgrading to the latest
0e400e45fa5bef7103232d78fc7a54f7390e03d8Jonathan Scudder This guide focuses on 3.4.1 API compatibility. It <strong>does not
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major describe new features added in 3.5.0</strong>.
0e400e45fa5bef7103232d78fc7a54f7390e03d8Jonathan Scudder Refer to the updated <a href="index.html">Uploader user guide</a> for
0e400e45fa5bef7103232d78fc7a54f7390e03d8Jonathan Scudder If you are unable to upgrade due to unresolvable issues, you can use the
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <a href="../uploader-deprecated/index.html">`uploader-deprecated`</a>
0e400e45fa5bef7103232d78fc7a54f7390e03d8Jonathan Scudder module, which is equivalent to the 3.4.1 implementation. But be
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major aware that this module will be removed in a future version of YUI.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major<h2 id="overview">Overview of API changes from 3.4.1</h2>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major The architectural changes resulted in the deprecation, replacement, or
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major removal of some of the attributes, properties, methods and events from
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major 3.4.1 version of the Uploader. Here is a quick list of the changes most
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major likely to affect your upgrade:
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major<h3>Attribute changes</h3>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <th>Attribute in 3.4.1</th>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <th>Change in 3.5.0</th>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`buttonSkin`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td><strong>No longer exists.</strong> The Uploader in Flash mode is now always rendered
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major as transparent, overlaying a "Select Files" button that can be replaced
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major with any control (with any skin) using the `selectFilesButton` attribute.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`fileFilters`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>Only available when the Uploader is in <strong>Flash mode</strong>, and has no effect
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major when the Uploader is in HTML5 mode. If filtering by extension is needed
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major across all Uploader modes, it is best to implement it post-selection,
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major by validating individual elements in the `fileList`.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`log`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td><strong>No longer exists.</strong> All necessary uploader information is transmitted via
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel <td>`multiFiles`</td>
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel <td>Renamed to `multipleFiles`</td>
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel <td>`transparent`</td>
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunnington <td><strong>No longer exists.</strong> The Uploader in Flash mode is now always rendered as
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunnington a transparent overlay over a "Select Files" button that can be customized
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunnington or replaced with any control using the `selectFilesButton` attribute.</td>
9f3a7ab4a46ef847ea71ae3c876ab40aceb3051bPhill Cunnington<h3>Method changes</h3>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <th>Method in 3.4.1</th>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <th>Change in 3.5.0</th>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td>`cancel`</td>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td><strong>No longer exists</strong> on the Uploader instance. Instead, a `cancelUpload()` method is present on the instance of Uploader's queue, stored in `uploaderInstance.queue`.
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden (See the <a href="{{apiDocs}}/classes/Uploader.Queue.html#method_cancelUpload">API Docs</a> for more information).
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td>`clearFileList`</td>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td><strong>No longer exists</strong>. Instead, you can directly manipulate the `fileList`
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden attribute.</td>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td>`enable`</td>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td><strong>No longer exists</strong>. Instead, set the `enabled` attribute to either `true` or `false`.</td>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td>`disable`</td>
1cfd64a79fab3fd25cb92a0d463c8b986caee88fNeil Madden <td><strong>No longer exists</strong>. Instead, set the `enabled` attribute to either `true` or `false`.</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`removeFile`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td><strong>No longer exists</strong>. Instead, you can directly manipulate the `fileList`
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major attribute.</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`upload`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td><strong>The method signature has changed</strong>. The new `upload()` method takes
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major `file`, `url`, and `postVars` as arguments, where `file` is a references to an instance
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major of `Y.File` (can be obtained from the `fileList` attribute), `url` is the target URL
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major to upload the file to, and `postVars` is a set of key-value pairs specifying the variables
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major 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 <a href="{{apiDocs}}/classes/UploaderFlash.html#method_upload">API Docs</a> for more information).</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`uploadAll`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td><strong>The method signature has changed</strong>. The new `uploadAll()` method takes
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major `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 <a href="{{apiDocs}}/classes/UploaderFlash.html#method_uploadAll">API Docs</a> for more information).</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td>`uploadThese`</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major <td><strong>The method signature has changed</strong>. The new `uploadThese()` method takes
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major `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 <a href="{{apiDocs}}/classes/UploaderFlash.html#method_uploadThese">API Docs</a> for more information).</td>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major<h2 id="progressive-enhancement">Improved Progressive Enhancement</h2>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter MajorThe 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:
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Majorif (Y.Uploader.TYPE != "none") {
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major var uploaderInstance = new Y.Uploader(....); // Common configuration settings.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major if (Y.Uploader.TYPE == "html5") {
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major // Additional configuration settings for an HTML5 uploader,
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major // e.g. a drag-and-drop area specification, etc.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major else if (Y.Uploader.TYPE == "flash") {
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major // Flash-specific configuration settings,
a62d691262d0b1a55b3fc79eba377ac7bd1c0629jeff.schenk // e.g. a fileFilters setting, etc.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major // Render the uploader
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major uploaderInstance.render("#selectFilesButtonContainer");
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major // Don't render the uploader and use predefined basic functionality
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major // instead (e.g. a simple upload form field).
c3a2e5908d076b22137b3752d61be208824e624dJames Phillpotts<h2 id="backend-setup">Backend Setup</h2>
c3a2e5908d076b22137b3752d61be208824e624dJames PhillpottsThe 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 <a href="index.html#backend-setup">Backend Setup</a> section in the User Guide for more information, or read more about it on the <a href="http://www.html5rocks.com/en/tutorials/cors/#toc-handling-a-not-so-simple-request">HTML5Rocks website.</a>
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major<h2 id="help-me">What Did We Miss?</h2>
e0c96405853179a6ecb19d24834ccebb904f7789Jake Feasel Obviously, there were quite a few changes to Uploader from 3.4.1 to 3.5.0.
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel It's likely that we missed something here. If you experience trouble with
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel your upgrade and find this migration guide is missing something important,
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel please <a href="/projects/yui3/newticket">file a ticket</a> and we'll update
75be86af5f9fab607e4d013c8d65814f338e35d7Jake Feasel it as soon as possible.
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major Additional resources to help with the upgrade include the <a href="/forum">forums</a>,
e8721886dbfd32e88cc7077cbee4b6bb1b44b443Peter Major and the #yui IRC channel on freenode.net.