Getting Started

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

<!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/yahoo-dom-event/yahoo-dom-event.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/element/element-beta-min.js"></script> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/json/json-min.js"></script> <!-- Source files --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.2/build/uploader/uploader-experimental-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.5.2/build/uploader/assets/uploader.swf";

To get started with the Uploader Control, begin by placing it on the page. Create a <div> (or other element) placeholder into which you'l render your Uploader instance. In a typical usage scenario, you can set the width and height of the container to 0, since the Uploader is a purely functional component and does not have UI of its own (although it does display status messages that can be useful for debugging):

<div id="toBeReplaced" style="width:0px;height:0px"><br /> Unable to load Flash content. The YUI Charts Control requires Flash Player 9.0.45 or higher. <br /> </div>

Finally, instantiate the Uploader by passing the id of the container <div> to it:

var uploader = new YAHOO.widget.Uploader( "toBeReplaced" );

Using the Uploader

The Uploader has a number of methods that allow the developer to invoke the "Open File" dialog and 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);

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.
• 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
• 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 cancelled. The event object contains the following variables:
  • type: "uploadCancel"
  • id: the unique id of the file whose upload has been cancelled.
• 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:

• browse (allowMultiple:Boolean, extensionFilterArray:Array) : triggers the system "Open File" dialog. The arguments are:
  • allowMultiple:Boolean: if true, the user is allowed to select multiple files by holding Shift (or Apple) button.
  • extensionFilterArray:Array : an array of objects with the following child variables:
    • description:String: the description of a particular extension filter (e.g. "Images")
    • extensions:String: a semicolon-separated list of allowed extensions (e.g. "*.jpg; *.gif")
• 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 : The HTTP request method, either "GET" or "POST" ("GET" by default).
  • vars:Object : An object containing variables to be passed in the POST request along with the upload. (e.g. {foo: "bar", foo1: "bar1"}).
  • fieldName:String : The name of the variable containing 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.
  • uploadScriptPath:String : the URL of the upload script
  • method:String : The HTTP request method, either "GET" or "POST" ("GET" by default).
  • vars:Object : An object containing variables to be passed in the POST request along with the upload. (e.g. {foo: "bar", foo1: "bar1"}).
  • fieldName:String : The name of the variable containing 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, then all ongoing file uploads are canceled.
• clearFileList () : clears the upload queue. Unless clearFileList is called, all browse calls will keep adding files to the queue.
• removeFile (fileID:String) : remove a fle 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 GET request to the same directory as the directory the script lives in. Note that this requires write permissions to the directory the script lives in. Always consider security implications when setting such permissions.

<?php foreach ($_FILES as $fieldName => $file) { move_uploaded_file($file['tmp_name'], "./" . $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.
• Because of a known Flash bug, the Uploader running in Firefox in Windows does not send the correct cookies with the upload; instead of sending Firefox cookies, it sends Internet Explorer’s cookies for the respective domain. As a workaround, we suggest either using a cookieless upload method or appending document.cookie to the upload request.

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 ydn-javascript mailing list.

In addition, please visit the 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 YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.