Getting Started

To use the Uploader Control, include the following source files in your web page:

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script>
 
<!-- Source files -->
<script src="http://yui.yahooapis.com/2.9.0/build/uploader/uploader-min.js"></script>
 

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script src="http://yui.yahooapis.com/2.9.0/build/element/element-min.js"></script>
 
<!-- Source files -->
<script src="http://yui.yahooapis.com/2.9.0/build/uploader/uploader-min.js"></script>
 

By default, the file uploader.swf is expected in the assets directory relative to the location of the HTML page in which a Uploader Control instance will appear. If you wish use uploader.swf from yui.yahooapis.com, or if you'd like to place uploader.swf in a different location on your own server, you may specify a path (relative to the page or absolute) by setting the following variable:

YAHOO.widget.Uploader.SWFURL = "http://yui.yahooapis.com/2.9.0/build/uploader/assets/uploader.swf";
 

YAHOO.widget.Uploader.SWFURL = "http://yui.yahooapis.com/2.9.0/build/uploader/assets/uploader.swf";
 

To get started with the Uploader Control, begin by placing it on the page. Create a <div> (or other container element) placeholder into which you'll render your Uploader instance. The Uploader UI (an equivalent of the "Browse..." button) can be rendered in one of two ways: you can either pass a URL of a button sprite to the constructor, in which case the uploader will render as a button; if the URL argument is omitted, the uploader will render as a transparent layer that dispatches mouse events (see the examples), and it will be your responsibility to create the visual UI below it.

Note that the invocation of the "Browse" dialog is the only UI task reserved to the uploader. All other methods of the uploader (configuration methods, upload call, etc.) need to be called by your UI.

The width and height of the container should be set to the size that you want the uploader to be.

<div id="uploaderContainer" style="width:120px; height:50px"></div>
 

<div id="uploaderContainer" style="width:120px; height:50px"></div>
 

Let's render the uploader as a button. To do that, we will instantiate the Uploader by passing the id of the container <div> to it, and the URL of the button sprite:

var uploader = new YAHOO.widget.Uploader( "uploaderContainer", "assets/buttonSprite.jpg" );
 

var uploader = new YAHOO.widget.Uploader( "uploaderContainer", "assets/buttonSprite.jpg" );
 

The button sprite image has to be structured as follows: it should be four equal-sized button skins (each of the size corresponding to the size of the container div), stacked vertically, in the following order from top to bottom: the mouse-up skin, the mouse-over skin, the mouse-down skin, and the control-disabled skin.

Using the Uploader

The Uploader has a number of methods that allow the developer to manage the file queuing and upload process. The Uploader also dispatches various events for different aspects of the upload process.

• Listening for events
• Uploader methods
• Handling uploads on the server
• Uploader examples

Listening for events

In order to receive events from the Uploader, you need to add event listeners. For example, to add a listener for a fileSelect event, do the following:

uploader.addListener('fileSelect',onFileSelect);
 

uploader.addListener('fileSelect',onFileSelect);
 

This means that when the user selects the files using the "Open File" dialog, the onFileSelectfunction will be called and an event object will be passed to it. The following events are dispatched by the Uploader:

• contentReady: dispatched when the Uploader Flash file has successfully initialized. No event object is passed to the listener function. Note: do not call any methods on the Uploader until this event fires. Until this event is dispatched, the uploader is not read to accept function calls.
• fileSelect: dispatched when the user has finished selecting the files in the "Open File" dialog. Event object contains the following variables:
  • type: "fileSelect"
  • fileList: an array of objects with the following file information:
    • size: file size in bytes
    • cDate: creation date
    • mDate: modification date
    • name: file name (no full path is available)
    • id: unique file id, used for referencing the file when managing the upload or getting upload progress.
• uploadStart: dispatched when the upload of a specific file has started. The event object contains the following variables:
  • type: "uploadStart"
  • id: the unique id of the file that's started to upload.
• uploadProgress: dispatched when new information on the upload progress of a specific file is available. The event object contains the following variables:
  • type: "uploadProgress"
  • id: The unique id of the file being uploaded.
  • bytesLoaded: the number of bytes of the file uploaded so far
  • bytesTotal: the total size of the file
• uploadCancel: dispatched when a particular file upload is canceled. The event object contains the following variables:
  • type: "uploadCancel"
  • id: the unique id of the file whose upload has been canceled.
• uploadComplete: dispatched when the upload of a particular file is complete. The event object contains the following variables:
  • type: "uploadComplete"
  • id: the unique id of the file whose upload has been completed.
• uploadCompleteData: dispatched when the server returns data in response to the completed upload. The event object contains the following variables:
  • type: "uploadCompleteData"
  • id: the unique id of the file that was uploaded.
  • data: the raw data returned by the server in response to the upload
• uploadError: dispatched when an error occurs in the upload process. The event object contains the following variables:
  • type: "uploadError"
  • id: the id of the file whose upload resulted in the error.
  • status: The status message associated with the error

Uploader methods

The Uploader Control supports the following methods:

• setAllowLogging (allowLogging:Boolean) : Turns logging output on or off. If on, the uploader dispatches log messages to the YUI logger if one is available, and to the Flash trace file. If off, the uploader stays silent.
  • allowLogging:Boolean : if true, logging is turned on; if false, logging is turned off. By default, logging is turned off.
• setAllowMultipleFiles (allowMultipleFiles:Boolean) : Allows the user to select multiple files when browsing. The result of the file selection is the same independent of whether the user is allowed to select a single file or multiple ones; in case of a single file, the returned file list simply contains a single element. If multiple files are allowed, then after every browsing dialog, newly selected files are added to the existing file list. If multiple files are prohibited, the file list is reset every time the user browses and select a new file.
  • allowMultipleFiles:Boolean : if true, multiple file selection is allowed; if false, multiple file selection is turned off. By default, multiple file selection is turned off.
• setSimUploadLimit (simUploadLimit:int) : Sets the number of simultaneous uploads if automatic queue management with uploadAll() is used.
  • simUploadLimit:int : an integer between 1 and 5 specifying the number of simultaneous uploads. Uploading more than 5 files is not recommended and isn't possible under automatic queue management.
• setFileFilters (fileFilters:Array) : Sets filters on the file extensions that the user is allowed to select. On Windows, this is not a strict filter: the user can override it by entering "*.*" in the file name input field. For that reason, if it's important to you that file types are restricted, you should check them after selection on the client side, and after upload on the server side.
  • fileFilters:Array : An array consisting of sets of key value pairs, of the form: {extensions: "extensionString", description:"DescriptionString", [optional]macType:"macTypeString" }. The extension string should be a comma-delimited list of the string formatted as "*.xxx". For example, the following is a valid element of the fileFilters array: {extensions:"*.jpg;*.gif;*.png", description:"Images"}.
• upload (fileID:String, uploadScriptPath:String, method:String, vars:Object, fieldName:String) : triggers the upload of a specific file
  • fileID:String : the id of the file to start uploading
  • uploadScriptPath:String : the URL of the upload script
  • method:String : An optional string argument specifying the HTTP request method for uploading accompanying variables, either "GET" or "POST" ("GET" by default).
  • vars:Object : An optional argument, containing variables to be passed in the POST request along with the upload. (e.g. {var1: "value1", var2: "value2"}).
  • fieldName:String : An optional string argument, containing the name of the variable with the uploaded file data. The name is "Filedata" by default.
• uploadAll (uploadScriptPath:String, method:String, vars:Object, fieldName:String) : upload all selected files. The queue management is automatic, with the number of simultaneous uploads specified by setSimUploadLimit().
  • uploadScriptPath:String : the URL of the upload script
  • method:String : An optional string argument specifying the HTTP request method for uploading accompanying variables, either "GET" or "POST" ("GET" by default).
  • vars:Object : An optional argument, containing variables to be passed in the POST request along with the upload. (e.g. {var1: "value1", var2: "value2"}).
  • fieldName:String : An optional string argument, containing the name of the variable with the uploaded file data. The name is "Filedata" by default.
• cancel (fileID:String) : cancel the ongoing file upload.
  • fileID:String : the id of the file whose upload should be canceled. If no argument is passed, then all ongoing file uploads are canceled.
• enable () : enables the uploader UI (enabled by default). If the uploader is rendered as a button, the button responds to clicks and changes visual state. If the uploader is rendered as a transparent overlay, it dispatches events to JS when mouse actions occur.
• disable () : disables the uploader UI (enabled by default). If the uploader is rendered as a button, the button stops respondin to hover and clicks and switches to the "disabled" skin in the button sprite.If the uploader is rendered as a transparent overlay, it stops dispatching events to JS when mouse actions occur.
• clearFileList () : clears the upload queue. When multiple file selection is disallowed, the file list is cleared between each invocation of the "Browse" dialog.
• removeFile (fileID:String) : remove a file with a specific file id from the queue.
  • fileID:String : the id of the file to remove from the queue

Handling uploads on the server

There are many ways of handling the request on the server. The following example uses PHP to write submissions from an HTTP POST request to the same directory as the directory the script lives in. Note that this requires write permissions to that directory. Always consider security implications when setting such permissions.

foreach ($_FILES as $fieldName => $file) {
    move_uploaded_file($file['tmp_name'], "./" . strip_tags(basename($file['name'])));
    echo (" ");
}
 
 

foreach ($_FILES as $fieldName => $file) {
    move_uploaded_file($file['tmp_name'], "./" . strip_tags(basename($file['name'])));
    echo (" ");
}
 
 

Uploader limitations

• The Uploader can only send data to servers in the same security sandbox as the uploader.swf file. If uploader.swf hosted by yui.yahooapis.com is used, then the server must contain a cross-domain permissions file allowing yui.yahooapis.com to upload files.  By default, Uploader looks for uploader.swf in the assets directory in the same path as uploader.js, so if you’re loading Uploader from yui.yahooapis.com you will be affected by this issue.
• The intended behavior of the uploader is not to send any cookies with its requests. Due to a limitation of the Windows networking library, when running in IE, the uploader sends the cookies with the upload. However, you cannot rely on this behavior for authentication, because it's absent in other browsers. As a workaround, we suggest either using a cookieless upload method or appending document.cookie to the upload request.
• There are some known issues around keyboard interaction with the uploader. In particular, when the uploader is rendered as a transparent layer, it does not respond to keyboard presses - only mouse functionality is available. When the uploader is rendered as an image, it receives "Space" and "Enter" key presses as triggers, but only if the focus is on the uploader component itself. Keyboard tabbing to the component behaves differently in different browsers.
• Because of Flash limitations, the uploader does not support basic authentication.
• Because of Flash limitations, the uploader behavior when working through a proxy server is inconsistent and unreliable.
• When uploading to HTTPS servers, be aware that Flash does not support self-signed certificates. You would need to obtain certificates from a recognized certificate authority.

Uploader examples

For further exploration of the uploader components, take a look at its example files. Note that in order to run these examples, you will need to copy them to your own web space and have a server capable of accepting uploads.

Support & Community

The YUI Library and related topics are discussed on the on the YUILibrary.com forums.

Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.