<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Uploader</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
<link rel="stylesheet" href="../assets/css/main.css">
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
<script src="../../build/yui/yui-min.js"></script>
</head>
<body>
<!--
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
-->
<div id="doc">
<div id="hd">
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
</div>
<a href="#toc" class="jump">Jump to Table of Contents</a>
<h1>Uploader</h1>
<div class="yui3-g">
<div class="yui3-u-3-4">
<div id="main">
<div class="content"><style type="text/css">
.notice {
background: #faf3d1;
border: 1px solid #eac9a9;
-moz-border-radius: 3px;
-webkit-border-radius: 3px;
border-radius: px;
padding: 0 1em;
-moz-box-shadow: 0 0 5px #ccc8b3;
-webkit-box-shadow: 0 0 5px #ccc8b3;
box-shadow: 0 0 5px #ccc8b3;
margin-bottom: 1em;
}
.notice h2 {
margin-top: .6em;
}
.only {
vertical-align: super;
font-size: 9px;
background: #faf3d1;
}
</style>
<div class="intro">
<p><strong>The YUI Uploader leverages HTML5+XMLHttpRequest 2 or Flash to provide file upload functionality beyond the basic HTTP <code><input type='file'></code> capabilities.</strong> Specifically, the Uploader allows for:
<ol>
<li> <strong>Multiple file selection</strong> in a single "Open File" dialog.</li>
<li> <strong>Dragging-and-dropping files</strong> into the browser (when used in HTML5 mode).</li>
<li> <strong>Automatic upload queue management</strong> with fine-grained control.</li>
<li> <strong>Upload progress tracking</strong>, both on a per-file and a per-queue basis.</li>
<li> <strong>A range of available file metadata</strong>: filename, size, date created, and date modified.</li>
<li> A set of <strong>events dispatched on various aspects of the file upload process</strong>: file selection, upload progress, upload completion, data return, and upload errors.</li>
<li> Inclusion of <strong>additional data in the file upload POST request</strong>, on a file-by-file basis.</li>
<li> <strong>Keyboard accessibility</strong> both in HTML5 and in Flash modes.</li>
</ol>
</div>
<div class="notice">
<h2 id="migration-intro">Upgrading from version 3.4.1 or older?</h2>
<p>
Uploader has been refactored for 3.5.0. Parts of its API have changed in backward-incompatible ways.
</p>
<p>
Read the <a href="migration.html">3.5.0 Migration Guide</a> for tips on a smooth transition.
If you still run into issues, please <a href="../../../projects/yui3/newticket/">file a ticket</a>.
</p>
<p>
If you are unable to upgrade due to unresolvable issues, you can use the
<a href="../uploader-deprecated/index.html"><code>uploader-deprecated</code></a>
module suite, which is equivalent to the 3.4.1 implementation. But be
aware that this module will be removed in a future version of YUI.
</p>
</div>
<h2 id="getting-started">Getting Started</h2>
<p>
To include the source files for Uploader and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>
<pre class="code prettyprint"><script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('uploader', function (Y) {
// Uploader is available and ready for use. Add implementation
// code here.
});
</script></pre>
<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
</p>
<div class="intro">
<h2 id="uploader-usage-notes-for-the-flash-mode">Uploader Usage Notes for the Flash mode</h2>
<ul>
<li>Because of security requirements of the Flash Player, the <strong>Uploader in Flash mode must receive a direct user input</strong> in order to initiate file browsing.</li>
<li><strong>The target server for file uploads must include a <code>crossdomain.xml</code> file</strong> that allows access from the location where the uploader SWF file is hosted.
See more in the <a href="#backend-setup">Backend Setup</a> section below, or read the <a href="http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html">crossdomain specification on Adobe's website</a>.</li>
<li><strong>The relative URLs to the target server are resolved differently in the Flash mode</strong> than they are in the HTML5 mode. In Flash mode, the URLs
are resolved relatively to the location of the SWF file, whereas in HTML5 mode, they are resolved relatively to the location of the web page. It is best to
avoid using relative URLs for upload targets and use absolute URLs instead.</li>
<li>The body of the server response to the Flash upload must be greater than 0 bytes. If its length is 0, then the upload is not registered as complete.</li>
<li>Because of limitations of the Flash Player, the <strong>Uploader in Flash mode does not transmit session data (cookies)</strong> in the header of the POST requests it sends to the server. In order to transmit the session data, the developer will need to programmatically extract it from the DOM and send as part of the body of the POST request.</li>
<li>The <strong>Uploader SWF should always be served from an HTTP server</strong> due to Flash Player's restricted local security model.</li>
<li>The <strong>Uploader control should not be placed in a container with <code>visibility</code> set to <code>hidden</code>, or <code>display</code> set to <code>none</code></strong>, whether at initialization of the page, or at any subsequent time. Because of how the Flash Player is instantiated, setting these properties to these values will result in the loss of communication between the Flash player and the DOM. If it's necessary to hide the instance of the Uploader on the page, its width and height should be set to 0.</li>
<li>The <strong>Uploader requires Flash Player 10.1 or higher</strong>. The latest version of Flash Player is available at the <a href="http://www.adobe.com/go/getflashplayer">Adobe Flash Player Download Center</a>.</li>
<li>Because of a long-standing bug in Internet Explorer, the <strong>Uploader SWF does not function properly in IE when loaded from local cache</strong>. For that reason, in IE, the default URL for the SWF is appended with a random GET parameter to prevent loading from cache.</li>
</ul>
</div>
<div class="intro">
<h2 id="uploader-usage-notes-for-the-html5-mode">Uploader Usage Notes for the HTML5 mode</h2>
<ul>
<li>Because of security requirements of crossorigin requests in XMLHttpRequest Level 2, the <strong>Uploader in HTML5 mode sends out a preflight <code>OPTIONS</code> request to the target server</strong> for file uploads (if the target server is different from the one that is hosting the page originating the request). See the <a href="#backend-setup">Backend Setup</a> section below for more information, or read more about CORS on the <a href="http://www.html5rocks.com/en/tutorials/cors/#toc-handling-a-not-so-simple-request">HTML5Rocks website.</a></li>
<li>Because of variations in browser support for multiple concurrent XMLHttpRequests, <strong>we recommend limiting the number of simultaneous uploads to 2</strong>.</li>
</ul>
</div>
<h2 id="using-the-uploader">Using the Uploader</h2>
<p>In this section, we'll describe how to use the uploader in detail. First, let's look at the structure of the uploader module under the hood.</p>
<h3 id="anatomy-of-the-uploader">Anatomy of the Uploader</h3>
<h4 id="progressive-enhancement">Progressive Enhancement</h4>
<p>The Uploader consists of two classes, one of which is picked dynamically based on the functionality available on the end user's computer. For that reason, <code>Y.Uploader</code> is an alias that is dynamically assigned either to the <code>Y.UploaderHTML5</code> (for browsers that implement <em>XMLHttpRequest Level 2</em>) or <code>Y.UploaderFlash</code> (for browsers that include the Flash player plugin), or otherwise left as an unpopulated namespace when neither functionality is available. Before instantiating the Uploader, the developer can easily determine which of the three options has been loaded by checking the static <code>Y.Uploader.TYPE</code> property. This property resolves to either <code>"html5"</code>, <code>"flash"</code>, or <code>"none"</code>, and allows the developer to configure the uploader appropriately or otherwise load a different UI.
</p>
<p>Due to the limitations of the Flash player, it is only possible to initiate the file selection dialog for Flash-supported file uploads with a direct user input to the Flash player. For that reason, and to maintain the API and configuration consistency, the Uploader is implemented as a "Select Files" button widget in both the HTML5 and the Flash modes. In case of HTML5 uploader, the interaction events are dispatched by the underlying UI control, whereas in case of the Flash uploader, a transparent Flash player overlay is placed on top of the control and captures all mouse events directly. The underlying UI control is customizable by the developer (the <code>selectFilesButton</code> attribute).
<h4 id="hybrid-structure">Hybrid structure</h4>
<p>In Flash mode, the Uploader uses the native functionality of the widely adopted Adobe Flash player to provide methods for sending
multiple files to the server and tracking the progress of the uploads. In order to control the Flash player, the Uploader uses the Flash player's built-in <code>ExternalInterface</code> class for communicating with JavaScript. <code>ExternalInterface</code> allows JavaScript to call exposed methods on an instance of a Flash player, and allows the instance of the Flash player to call arbitrary global methods in the global JavaScript space.
</p>
<p>
In order to properly instantiate the Flash player and communicate with it, the Uploader uses YUI SWF utility. The SWF utility
encapsulates the instance of the Flash player and standardizes communication with it (e.g., all Flash player method calls are
wrapped in SWF's <code>callSWF</code> function; correspondingly, all method calls from the Flash player are exposed as events dispatched by SWF.)
</p>
<h3 id="instantiating-and-configuring-the-uploader">Instantiating and Configuring the Uploader</h3>
<h4 id="simple-instantiation">Simple Instantiation</h4>
<p>To place the Uploader on the page, simply create a new instance of <code>Y.Uploader</code> and render it to the container in which it should be placed.
Since <code>Y.Uploader</code> may not resolve to a fully-featured module if the required functionality is missing, test that the <code>Y.Uploader.TYPE</code> property
is not set to <code>"none"</code> first.
It is recommended that you set fixed dimensions in the configurations for the uploader widget, because the underlying button UI control
is by default sized to 100% of the width and height of its parent:</p>
<pre class="code prettyprint">YUI({...}).use('uploader',function (Y) {
if (Y.Uploader.TYPE != "none") {
var uploader = new Y.Uploader({width: "300px",
height: "40px"}).render("#uploaderContainerID");
}
});</pre>
<h4 id="manual-uploader-type-override">Manual Uploader Type Override</h4>
<p>With the above instantiation, you are allowing the Uploader to automatically choose whether to use <code>UploaderHTML5</code> or <code>UploaderFlash</code> as the underlying module. You can always use those modules directly or manually override the alias as follows:
<pre class="code prettyprint">YUI({...}).use('uploader','uploader-flash', function (Y) {
Y.Uploader = Y.UploaderFlash;
// or
Y.Uploader = Y.UploaderHTML5;
var uploader = new Y.Uploader(...);
});</pre>
</p>
<h4 id="features-based-on-available-functionality">Features Based on Available Functionality</h4>
<p>You can further use the <code>Y.Uploader.TYPE</code> property to add functionality-specific features to the Uploader based on whether HTML5 or Flash are available. For instance, in the following code snippet, if the Uploader is in HTML5 mode, we assign it a drag-and-drop area where files can be dragged directly into the browser
(functionality which is unavailable in Flash). If it's in Flash mode, we provide a <code>fileFilters</code> configuration which allows the selection dialog to filter
files by extension (functionality only available in Flash):
<pre class="code prettyprint">YUI({...}).use('uploader', function (Y) {
var uploader = new Y.Uploader(...);
if (Y.Uploader.TYPE == "html5") {
uploader.set("dragAndDropArea", "#divContainer");
uploader.render("#selectFilesButtonContainer");
}
else if (Y.Uploader.TYPE == "flash") {
uploader.set("fileFilters", [{description:"Images", extensions:"*.jpg;*.png;*.gif"},
{description:"Videos", extensions:"*.avi;*.mov;*.mpg"}]);
uploader.render("#selectFilesButtonContainer");
}
else {
Y.log("No Flash or HTML5 capabilities detected.");
}
});</pre>
<h4 id="uploader-configuration-attributes">Uploader Configuration Attributes</h4>
<p>The following configuration attributes are specific to the Uploader:</p>
<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>appendNewFiles</code></td>
<td>A Boolean indicating whether newly selected files should be appended to the existing file list, or whether they should replace it.</td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>buttonClassNames</code></td>
<td>The names of CSS classes that correspond to different button states of the "Select Files" control. These classes are assigned to the "Select Files" control based on the mouse states reported by the Flash player or by the state of the HTML5 Uploader. The keys for the class names are:
<ul>
<li><code>hover</code>: the class corresponding to mouse hovering over the "Select Files" button.<span class="only">UploaderFlash</span></li>
<li><code>active</code>: the class corresponding to mouse down state of the "Select Files" button.<span class="only">UploaderFlash</span></li>
<li><code>disabled</code>: the class corresponding to the disabled state of the "Select Files" button.</li>
<li><code>focus</code>: the class corresponding to the focused state of the "Select Files" button.<span class="only">UploaderFlash</span></li>
</ul>
</td>
<td><pre>{
hover:
"yui3-button-hover",
active:
"yui3-button-active",
disabled:
"yui3-button-disabled",
focus:
"yui3-button-selected"
}</pre>
</td>
</tr>
<tr>
<td><code>dragAndDropArea</code><span class="only">UploaderHTML5</span></td>
<td>The node that serves as the drop target for files.</td>
<td><code>null</code></td>
</tr>
<tr>
<td><code>enabled</code></td>
<td>A Boolean indicating whether the uploader is enabled or disabled for user input.</td>
<td><code>true</code></td>
</tr>
<tr>
<td><code>errorAction</code></td>
<td>The action performed when an upload error occurs for a specific file being uploaded. The possible values are:
<ul>
<li><code>Y.Uploader.Queue.CONTINUE</code>: the error is ignored and the upload process is continued.</li>
<li><code>Y.Uploader.Queue.STOP</code>: the upload process is stopped as soon as any other parallel file uploads are finished.</li>
<li><code>Y.Uploader.Queue.RESTART_ASAP</code>: the file is added back to the front of the queue.</li>
<li><code>Y.Uploader.Queue.RESTART_AFTER</code>: the file is added to the back of the queue.</li>
</ul>
</td>
<td><code>Y.Uploader.Queue.CONTINUE</code></td>
</tr>
<tr>
<td><code>fileFieldName</code></td>
<td>A String specifying what should be the POST field name for the file content in the upload request.</td>
<td><code>"Filedata"</code></td>
</tr>
<tr>
<td><code>fileFilters</code><span class="only">UploaderFlash</span></td>
<td>An array indicating what fileFilters should be applied to the file selection dialog. Each element in the
array should be an object with the following key-value pairs:
<pre class="code prettyprint">{ description : String,
extensions: String of the form"."ext1;.ext2;*.ext3;..."
}</pre>
</td>
<td><code>null</code></td>
</tr>
<tr>
<td><code>fileList</code></td>
<td>The array of files to be uploaded. All elements in the array must be instances of <code>Y.File</code> and be properly instantiated
depending on whether <code>UploaderHTML5</code> or <code>UploaderFlash</code> is being used.</td>
<td><code>[]</code></td>
</tr>
<tr>
<td><code>multipleFiles</code></td>
<td>A Boolean indicating whether multiple file selection is enabled.</td>
<td><code>false</code></td>
</tr>
<tr>
<td><code>postVarsPerFile</code></td>
<td>An object, keyed by fileId, containing sets of key-value pairs that should be passed as POST variables along with each
corresponding file. This attribute is only used if no POST variables are specified in the upload method call.</td>
<td><code>{}</code></td>
</tr>
<tr>
<td><code>selectButtonLabel</code></td>
<td>The label for the "Select Files" widget. This is the value that replaces the <code>{selectButtonLabel}</code> token in the
<code>Y.Uploader.SELECT_FILES_BUTTON</code> template.</td>
<td><code>"Select Files"</code></td>
</tr>
<tr>
<td><code>selectFilesButton</code></td>
<td>The widget that serves as the "Select Files" control for the file uploader.</td>
<td><code>HTML Button with YUI3 CSS Button skin</code></td>
</tr>
<tr>
<td><code>simLimit</code></td>
<td>The number of files that can be uploaded simultaneously if the automatic queue management is used.
This value can be in the range between 2 and 5, with the value of 1 or 2 recommended.</td>
<td><code>2</code></td>
</tr>
<tr>
<td><code>swfURL</code><span class="only">UploaderFlash</span></td>
<td>The URL to the SWF file of the flash uploader. A copy local to the server that hosts the page on
which the uploader appears (rather than a CDN-sourced uploader) is recommended.</td>
<td><code>CDN Prefix</code> + <code>uploader/assets/flashuploader.swf</code></td>
</tr>
<tr>
<td><code>tabElements</code><span class="only">UploaderFlash</span></td>
<td>The <code>id</code>'s or Node references of the DOM elements that precede and follow the "Select Files" button in the tab order.
Specifying these allows keyboard navigation to and from the Flash player layer of the uploader. The two keys
corresponding to the DOM elements are:
<ul>
<li><code>from</code>: the id or the Node reference corresponding to the DOM element that precedes the Select Files button in the tab order.</li>
<li><code>to</code>: the id or the Node reference corresponding to the DOM element that follows the Select Files button in the tab order.</li>
</ul>
</td>
<td><code>null</code></td>
</tr>
<tr>
<td><code>uploadURL</code></td>
<td>The URL to which file upload requested are POSTed. Only used if a different url is not passed to the upload method call.</td>
<td><code>""</code></td>
</tr>
</tbody>
</table>
<h4 id="multiple-file-selection">Multiple file selection</h4>
<p>While the file selection dialog in the Uploader is standard for the user's specific operating system, you can specify whether you want the user to be able to select multiple files, or just one:</p>
<pre class="code prettyprint">uploader.set("multipleFiles", true);</pre>
<h3 id="the-upload-process">The Upload Process</h3>
<h4 id="automatic-queue-management">Automatic Queue Management</h4>
<p> After the user has selected a file (or files) to be uploaded, the selected file list is places into the <code>fileList</code> attribute of the Uploader. At that point,
you can either have the user initialize the actual upload process, or initialize it automatically, without any additional user action.</p>
<p> Each of the selected files is uploaded in its own POST request. You can either upload each file individually, and manage the queue on your own, or use the Uploader's built-in queue management. To upload a single file "manually" (without using automatic queue management), the following method call can be made:</p>
<pre class="code prettyprint">var firstFile = uploader.get("fileList")[0];
uploader.upload(firstFile, "http://url.to/upload.php", {postvar1: "foo", postvar2: "bar"});</pre>
<p> To upload all files using the built-in queue manager, you can call the <code>uploadAll()</code> method:</p>
<pre class="code prettyprint">uploader.uploadAll("http://url.to/upload.php");</pre>
<p> You can also upload a subset of the provided files, using the <code>uploadThese()</code> method: </p>
<pre class="code prettyprint">var firstFive = uploader.get("fileList").slice(0,5);
uploader.uploadThese(firstFive, "upload.php");</pre>
<h4 id="monitoring-upload-progress">Monitoring Upload Progress</h4>
<p>When using the automatic queue management, you can monitor the overall upload progress by subscribing to the <code>totaluploadprogress</code> event, which reports the number of bytes uploaded, the total number of bytes, and the percentage of the upload completed:</p>
<pre class="code prettyprint">uploader.on("totaluploadprogress", reportProgress);
function reportProgress (event) {
Y.log("Bytes uploaded: " + event.bytesLoaded);
Y.log("Bytes remaining: " + (event.bytesTotal - event.bytesLoaded));
Y.log("Percent uploaded: " + event.percentLoaded);
}</pre>
<p>Individual file upload progress is also reported, via the <code>uploadprogress</code>, <code>uploadcomplete</code>, and <code>uploaderror</code> events described below.</p>
<h4 id="custom-queue-control">Custom Queue Control</h4>
<p>During the automatic queue management of multiple files, you can call various methods on the Uploader queue (available as <code>uploaderInstance.queue</code>)
in order to control the file upload. The methods available to you include:
<ul>
<li><strong>addToQueueTop()</strong> and <strong>addToQueueBottom()</strong>: allow you to include additional files in the upload queue, either at the
beginning or at the end.</li>
<li><strong>cancelUpload()</strong>: cancel a specific file's upload. If no arguments are passed, all of the uploads are cancelled.</li>
<li><strong>forceReupload()</strong>: if a particular file is stuck in an ongoing upload without any progress events, you can force its reupload.
This method is equivalent to cancelling the file's upload and then adding it back to the queue.</li>
<li><strong>pauseUpload()</strong>: complete all currently ongoing uploads, but ceases starting new ones, until <strong>startUpload()</strong> is called.</li>
</ul>
<p>For more information, see the <a href="http://yuilibrary.com/yui/docs/api/classes/Uploader.Queue.html">API Docs for Uploader.Queue</a>.</p>
<h3 id="uploader-events">Uploader events</h3>
<p>Uploader fires the following events during operation:</p>
<table>
<thead>
<tr>
<th>Event</th>
<th>Cause</th>
<th>Payload</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>alluploadscomplete</code></td>
<td>Signals that the upload process of the entire file list has been completed.</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>click</code><span class="only">UploaderFlash</span></td>
<td>Signals that a mouse has been clicked over the <code>Select Files</code> button.</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>dragenter</code><span class="only">UploaderHTML5</span></td>
<td>Signals that a dragged object has entered into the uploader's associated drag-and-drop area (if one is specified).</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>dragleave</code><span class="only">UploaderHTML5</span></td>
<td>Signals that a dragged object has entered into the uploader's associated drag-and-drop area (if one is specified).</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>dragleave</code><span class="only">UploaderHTML5</span></td>
<td>Signals that an object has been dragged off of the uploader's associated drag-and-drop area (if one is specified).</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>dragover</code><span class="only">UploaderHTML5</span></td>
<td>Signals that an object has been dragged over the uploader's associated drag-and-drop area (if one is specified).</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>drop</code><span class="only">UploaderHTML5</span></td>
<td>Signals that an object has been dropped over the uploader's associated drag-and-drop area (if one is specified).</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>fileselect</code></td>
<td>Signals that files have been selected.</td>
<td><code>fileList</code>: An Array of files selected by the user, encapsulated in <code>Y.File</code></td>
</tr>
<tr>
<td><code>fileuploadstart</code></td>
<td>Signals that the upload of multiple files has been started.</td>
<td><p><code>file</code>: A reference to the instance of <code>Y.File</code> that dispatched the event.</p>
<p><code>originEvent</code>: The original event dispatched by <code>Y.File</code></p>
</td>
</tr>
<tr>
<td><code>mousedown</code><span class="only">UploaderFlash</span></td>
<td>Signals that a mouse has been pressed over the <code>Select Files</code> button.</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>mouseenter</code><span class="only">UploaderFlash</span></td>
<td>Signals that a mouse has begun hovering over the <code>Select Files</code> button.</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>mouseleave</code><span class="only">UploaderFlash</span></td>
<td>Signals that a mouse has stopped hovering over the <code>Select Files</code> button.</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>mouseup</code><span class="only">UploaderFlash</span></td>
<td>Signals that a mouse has been released over the <code>Select Files</code> button.</td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>totaluploadprogress</code></td>
<td>Reports on the total upload progress of the file list.</td>
<td><p><code>bytesLoaded</code>: The number of bytes of the file list that has been uploaded.</p>
<p><code>bytesTotal</code>: The total number of bytes in the file list.</p>
<p><code>percentLoaded</code>: The fraction of the file list that has been uploaded, out of 100.</p>
</td>
</tr>
<tr>
<td><code>uploadcomplete</code></td>
<td>Signals that a single file upload has been completed.</td>
<td><p><code>originEvent</code>: The original event dispatched by the instance of <code>Y.File</code>.</p>
<p><code>file</code>: The pointer to the instance of <code>Y.File</code> that dispatched the event.</p>
<p><code>data</code>: The data returned by the server.</p>
</td>
</tr>
<tr>
<td><code>uploaderror</code></td>
<td>Signals that a error has occurred in a specific file's upload process.</td>
<td><p><code>originEvent</code>: The original event dispatched by the Uploader.</p>
<p><code>file</code>: The pointer to the instance of <code>Y.File</code> that dispatched the event.</p>
<p><code>source</code>: Either 'io' or 'http'.<span class="only">UploaderFlash</span></p>
<p><code>message</code>: The message corresponding to the error. In case of HTTP errors contains the status code.<span class="only">UploaderFlash</span></p>
<p><code>status</code>: The status reported by the XMLHttpRequest object.<span class="only">UploaderHTML5</span></p>
<p><code>statusText</code>: The status text reported by the XMLHttpRequest object.<span class="only">UploaderHTML5</span></p>
</td>
</tr>
<tr>
<td><code>uploadprogress</code></td>
<td>Reports on upload progress of a specific file.</td>
<td><p><code>file</code>: The pointer to the instance of <code>Y.File</code> that dispatched the event.</p>
<p><code>bytesLoaded</code>: The number of bytes of the file that has been uploaded.</p>
<p><code>bytesTotal</code>: The total number of bytes in the file.</p>
<p><code>percentLoaded</code>: The fraction of the file that has been uploaded, out of 100.</p>
<p><code>originEvent</code>: The original event dispatched by the uploader transport.</p>
</td>
</tr>
<tr>
<td><code>uploadstart</code></td>
<td>Signals that an upload of multiple files has been started.</td>
<td><code>None</code></td>
</tr>
</tbody>
</table>
<p>See the API documentation for <a href="http://yuilibrary.com/yui/docs/api/classes/UploaderHTML5.html">UploaderHTML5</a> and <a href="http://yuilibrary.com/yui/docs/api/classes/UploaderFlash.html">UploaderFlash</a> for a complete documentation of the Uploader events, methods, attributes, and properties.</p>
<h3 id="backend-setup">Backend Setup</h3>
<h4 id="setting-up-the-backend-for-flash">Setting up the backend for Flash</h4>
<p>Unless the server receiving the file uploads is located on the same domain as the SWF file that is dispatching the uploads, the receiving server must include a <strong>crossdomain.xml</strong> file allowing the server on which the SWF is located to make requests to it. Consider, for instance, the <a href="http://www.yahoo.com/crossdomain.xml"><strong>crossdomain.xml</strong> policy file on yahoo.com</a>. It looks as follows:</p>
<pre class="code prettyprint"><cross-domain-policy>
<allow-access-from domain="*.yahoo.com" secure="false"/>
</cross-domain-policy></pre>
<p>The <code>allow-access-from</code> parameter specifies which domains hosting SWFs can access yahoo.com: in this case, only subdomains of yahoo.com are allowed to do so. Note, for instance, that <a href="http://www.cnn.com/crossdomain.xml">CNN.com's list</a> is considerably larger.</p>
<p>If you are planning on using the CDN-hosted Uploader SWF, your crossdomain.xml file might look something like this:</p>
<pre class="code prettyprint"><cross-domain-policy>
<allow-access-from domain="yui.yahooapis.com" secure="false"/>
</cross-domain-policy></pre>
<h4 id="setting-up-the-backend-for-html5">Setting up the backend for HTML5</h4>
<p>The security policy for XMLHttpRequest Level 2 cross-domain requests is a little bit trickier. Instead of using separate files, XHR2 uses server-supplied headers to determine whether a request can be made. Before the regular POST request, XHR submits a preflight OPTIONS request with an <code>Origin</code> parameter. In response, it expects a <code>Access-Control-Allow-Origin</code> header with a wildcard or a URL matching the <code>Origin</code> parameter it sent. This header can be set either through the web server you are using, or directly by the script output. For instance, here is a PHP example that replies to the OPTIONS requests with a header allowing all origins:</p>
<pre class="code prettyprint">if ($_SERVER['REQUEST_METHOD'] == 'OPTIONS') {
header('Access-Control-Allow-Origin: *');
exit;
}</pre>
<p>Note that the actual response must also contain the <code>Access-Control-Allow-Origin</code> header.</p>
<p>To learn more about XHR2 cross-domain requests, read <a href="http://www.html5rocks.com/en/tutorials/cors/">this helpful tutorial on html5rocks.com</a>.</p>
</div>
</div>
</div>
<div class="yui3-u-1-4">
<div class="sidebar">
<div id="toc" class="sidebox">
<div class="hd">
<h2 class="no-toc">Table of Contents</h2>
</div>
<div class="bd">
<ul class="toc">
<li>
<a href="#migration-intro">Upgrading from version 3.4.1 or older?</a>
</li>
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#uploader-usage-notes-for-the-flash-mode">Uploader Usage Notes for the Flash mode</a>
</li>
<li>
<a href="#uploader-usage-notes-for-the-html5-mode">Uploader Usage Notes for the HTML5 mode</a>
</li>
<li>
<a href="#using-the-uploader">Using the Uploader</a>
<ul class="toc">
<li>
<a href="#anatomy-of-the-uploader">Anatomy of the Uploader</a>
<ul class="toc">
<li>
<a href="#progressive-enhancement">Progressive Enhancement</a>
</li>
<li>
<a href="#hybrid-structure">Hybrid structure</a>
</li>
</ul>
</li>
<li>
<a href="#instantiating-and-configuring-the-uploader">Instantiating and Configuring the Uploader</a>
<ul class="toc">
<li>
<a href="#simple-instantiation">Simple Instantiation</a>
</li>
<li>
<a href="#manual-uploader-type-override">Manual Uploader Type Override</a>
</li>
<li>
<a href="#features-based-on-available-functionality">Features Based on Available Functionality</a>
</li>
<li>
<a href="#uploader-configuration-attributes">Uploader Configuration Attributes</a>
</li>
<li>
<a href="#multiple-file-selection">Multiple file selection</a>
</li>
</ul>
</li>
<li>
<a href="#the-upload-process">The Upload Process</a>
<ul class="toc">
<li>
<a href="#automatic-queue-management">Automatic Queue Management</a>
</li>
<li>
<a href="#monitoring-upload-progress">Monitoring Upload Progress</a>
</li>
<li>
<a href="#custom-queue-control">Custom Queue Control</a>
</li>
</ul>
</li>
<li>
<a href="#uploader-events">Uploader events</a>
</li>
<li>
<a href="#backend-setup">Backend Setup</a>
<ul class="toc">
<li>
<a href="#setting-up-the-backend-for-flash">Setting up the backend for Flash</a>
</li>
<li>
<a href="#setting-up-the-backend-for-html5">Setting up the backend for HTML5</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="sidebox">
<div class="hd">
<h2 class="no-toc">Examples</h2>
</div>
<div class="bd">
<ul class="examples">
<li data-description="A simple multiple file uploader with progress tracking">
<a href="uploader-multiple.html">Simple Multiple Files Uploader with Progress Tracking</a>
</li>
<li data-description="A multiple file uploader with HTML5 Drag-and-Drop Support">
<a href="uploader-dd.html">Multiple Files Uploader with HTML5 Drag-and-Drop Support</a>
</li>
<li data-description="A multiple file uploader that submits additional POST vars with each file and receives data from the server">
<a href="uploader-data.html">Multiple Files Uploader with POST Variables and Server Data Retrieval</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>
<script>
YUI.Env.Tests = {
examples: [],
project: '../assets',
assets: '../assets/uploader',
name: 'uploader',
title: 'Uploader',
newWindow: '',
auto: false
};
YUI.Env.Tests.examples.push('uploader-multiple');
YUI.Env.Tests.examples.push('uploader-dd');
YUI.Env.Tests.examples.push('uploader-data');
</script>
<script src="../assets/yui/test-runner.js"></script>
</body>
</html>