Uploader API

Creating an Uploader

To instantiate a new Uploader on your page using the recommended progressive enhancement feature:


var myUploader = fluid.uploader(container, options);

Returns: A Uploader component object. The resulting type may be either fluid.uploader.multiFileUploader or fluid.uploader.singleFileUploader depending on the capabilities of your user's browser. If you're programmatically calling methods on the Uploader, be sure to check its typeName or use duck typing first.

Parameters

container

The container is a CSS-based selector, single-element jQuery object, or DOM element that identifies the root DOM node of the Uploader markup.

options

The options object is an optional data structure that configures the Uploader, as described in the fluid:Options section below.

Supported Events

The Uploader fires the following events (for more information about events in the Fluid Framework, see Events for Component Users):

Event	Type	Description	Parameters	Parameter Description

Event	Type	Description	Parameters	Parameter Description
`afterReady`	default	This event is fired when the Flash (swf) object is instantiated and ready.	none
`onFileDialog`	default	The event is fired when the OS File Open dialog is displayed.	none
`onFilesSelected`	default	The event is fired when files have been selected for addition to the file queue. HTML5 only.	`numFiles`	The number of files selected.
`onFileQueued`	default	The event is fired when files have been added to the file queue. Flash only.	none
`afterFileQueued`	default	This event is fired for each file that is queued after the File Selection Dialog window is closed.	`file`	`file`: the fluid:File object that has just been added to the queue.
`afterFileRemoved`	default	Event is fired for each file that is removed from the filequeue model	`file`	`fie`: the fluid:File object that was just removed from the queue
`onQueueError`	default	This event is fired for each file that was not queued after the File Selection Dialog window is closed.	`file, errorCode`	`file`: the fluid:File object that failed to be added to the queue. `errorCode [fluid:number]`: indication of the reason for the file not being added to the queue. Use that.swfUploader.QUEUE_ERROR to interpret the value. Note: A file may not be queued for several reasons such as, the file exceeds the file size, the file is empty or a file or queue limit has been exceeded.
`afterFileDialog`	default	This event fires after the File Selection Dialog window has been closed and all the selected files have been processed.	none
`onUploadStart`	default	This event at the beginning of the entire upload cycle.	`fileList`	`fileList`: a list of the fluid:File objects that will be uploaded to the server.
`onFileStart`	default	This event is fired immediately before the file is uploaded.	`file`	`file`: the fluid:File object that has started to be uploaded.
`onFileProgress`	default	This event is fired periodically by the upload manager during a file upload and is useful for providing UI updates on the page. Also keeps up-to-date the overall progress of the currently uploading batch.	`file, fileBytesComplete, fileTotalBytes`	`file`: the fluid:File Ooject for this progress event `fileBytesComplete` [fluid:number]: the number of bytes for the current file that have been uploaded to the server `fileTotalBytes` [fluid:number]: the total size of the file in bytes.
`onFileError`	default	This event is fired any time an individual file upload is interrupted or does not complete successfully.	`file, error, status, xhr`	`file`: the fluid:File object that errored. `error` [fluid:number]: whether the file failed because the user cancelled the upload or because of another file specific error Use fluid.uploader.fileStatusConstants to interpret the value. `status` [fluid:string]: xhr.status. 0 if the error occurs during the upload, otherwise, the HTTP status code. `xhr`: Defaults to the ActiveXObject when available (IE), the XMLHttpRequest otherwise.
`onFileSuccess`	default	This event is fired when an upload completes and the server returns a HTTP 200 status code.	`file, responseText, xhr`	`file`: the fluid:File object that has completed. `responseText`: the response text returned from the server. `xhr`: Defaults to the ActiveXObject when available (IE), the XMLHttpRequest otherwise.
`afterFileComplete`	default	This event is fired for each file uploaded whether or not the file is uploaded successfully (`onFileSuccess`) or the file failed to upload (`onFileError`). At this point the upload process for the currently uploading file is complete and the upload for the next file in the queue is started.	`file`	`file`: the fluid:File object that was successfully uploaded.
`afterUploadComplete`	default	This event is fired at the end of an upload cycle when all the files have either been uploaded, failed to upload, the user stopped the upload cycle, or there was an unrecoverable error in the upload process and the upload cycle was stopped.	`fileList`	`fileList`: the list of fluid:File objects that "completed" (either succeeded or failed), in this upload.

File Objects

Many of the Uploader's events pass a File object as a parameter to the event listener. These objects provide useful information about the file, including its name, size in bytes, and its current status in the queue.

File object: a representation of each file in the file queue, as provided from the upload strategy. At the moment, the properties of this object will be slightly different depending on the strategy you're using. This will be addressed in a future release.

Regardless of the strategy, the following properties will be available:


  id : string,             // a unique id for each file in the queue
  name : string,           // The file name. The path is not provided.
  size : number,           // The file size in bytes
  filestatus : number      // The file's current status.
                           // Use fluid.uploader.fileStatusConstants to interpret the value.

File Status Constants

The Uploader offers a set of constants used to denote the status of a particular file in the queue. These can be used when querying the filestatus property of a fluid:File object.

Upload Error Constants	Description

Upload Error Constants	Description
fluid.uploader.errorConstants.HTTP_ERROR	An HTTP error occurred while uploading a file.
fluid.uploader.errorConstants.MISSING_UPLOAD_URL	The `uploadURL` was not correctly specified in the `uploadManager` options.
fluid.uploader.errorConstants.IO_ERROR	An IO error occurred while transferring the file.
fluid.uploader.errorConstants.SECURITY_ERROR	The upload caused a security error to occur.
fluid.uploader.errorConstants.UPLOAD_LIMIT_EXCEEDED	The user attempted to upload more files than allowed by the `fileUploadLimit}}option for the {{uploadManager`.
fluid.uploader.errorConstants.UPLOAD_FAILED	The Uploader was unable to start uploading the file to the server
fluid.uploader.errorConstants.SPECIFIED_FILE_ID_NOT_FOUND	This indicates an error in the Uploader and should be filed as a bug
fluid.uploader.errorConstants.FILE_VALIDATION_FAILED
fluid.uploader.errorConstants.FILE_CANCELLED	The upload was canceled by the user.
fluid.uploader.errorConstants.UPLOAD_STOPPED	The upload was stopped by the user.
File Status Constants
fluid.uploader.fileStatusConstants.QUEUED	The file is currently queued up and ready to be sent to the server.
fluid.uploader.fileStatusConstants.IN_PROGRESS	The file is currently being uploaded to the server.
fluid.uploader.fileStatusConstants.ERROR	An error occurred while trying to upload the file.
fluid.uploader.fileStatusConstants.COMPLETE	The file was successfully uploaded to the server.
fluid.uploader.fileStatusConstants.CANCELLED	The file was canceled by the user while in the process of being uploaded.

Options

The Uploader supports a "plug-and-play" architecture that allows for many of the sub-components of the Uploader to be swapped out for other components or your own custom components. The best example of this is the strategy component, which allows you to choose between the fluid.uploader.html5Strategy, the fluid.uploader.swfUploadStrategy, and the fluid.uploader.progressiveStrategy. However you can also replace the Progress subcomponent and the FileQueueView subcomponent, with a customized version you have implemented yourself.

The Uploader and its sub-components are also highly configurable; you can make many adjustments to the user experience through a combination of HTML, CSS and the built-in configuration options. To customize the component for your own needs, start with these out-of-the-box features. If you need more flexibility, feel free to to write your own sub-component.

In addition to the Uploader options, there are also options specifically for the FileQueueView, Progress, and strategy subcomponents.

Uploader Subcomponents:

Name	Description	Values	Default

Name	Description	Values	Default
`strategy`	The strategy for how files are uploaded to the server (e.g. HTML 5, Flash, etc.)	`"fluid.uploader.progressiveStrategy"`, `"fluid.uploader.html5Strategy"`, or `"fluid.uploader.swfUploadStrategy"`	`strategy: { type: "fluid.uploader.progressiveStrategy" }`
`fileQueueView`	Specifies the type of fileQueueView subcomponent to use. Currently there is only one fileQueueView sub-component.	"fluid.fileQueueView"	`fileQueueView: { type: "fluid.fileQueueView" }`
`totalProgressBar`	Specifies the type and options to use for the total progress bar.	See the Progress API documentation for a full descriptions of the available options.	`totalProgressBar: { type: "fluid.progress", options: { selectors: { progressBar: ".flc-uploader-queue-footer", (was ".flc-uploader-scroller-footer" in v1.0) displayElement: ".flc-uploader-total-progress", label: ".flc-uploader-total-progress-text", indicator: ".flc-uploader-total-progress", ariaElement: ".flc-uploader-total-progress" } } },`

Uploader Options:

Name	Description	Values	Default

Name	Description	Values	Default
`selectors`	Javascript object containing selectors for various fragments of the uploader markup		see #Selectors below
`listeners`	JavaScript object containing events and the listeners that are attached to them.	Keys in the object are event names, values are functions or arrays of functions.	See fluid:Supported Events
`focusWithEvent`	Javascript object containing selectors for markup elements that should obtain focus after certain #events.	Keys in the object are supported event names. Note: only specific methods in the Uploader have been factored to use this values.	`focusWithEvent: { afterFileDialog: "uploadButton", afterUploadStart: "pauseButton", afterUploadStop: "uploadButton" },`
`styles`	Specific class names used to achieve the look and feel of the different states of the Uploader		`styles: { disabled: "fl-uploader-disabled", hidden: "fl-uploader-hidden", dim: "fl-uploader-dim", totalProgress: "fl-uploader-total-progress-okay", totalProgressError: "fl-uploader-total-progress-errored" }`
`strings`	Strings that are used in the Uploader. Note: The strings that contain tokens (example: %curFileN) are passed through a string template parser.		strings: { progress: { fileUploadLimitLabel: "%fileUploadLimit %fileLabel maximum", toUploadLabel: "To upload: %fileCount %fileLabel (%totalBytes)", totalProgressLabel: "Uploading: %curFileN of %totalFilesN %fileLabel (%currBytes of %totalBytes)", completedLabel: "Uploaded: %curFileN of %totalFilesN %fileLabel (%totalCurrBytes)%errorString", numberOfErrors: ", %errorsN %errorLabel", singleFile: "file", pluralFiles: "files", singleError: "error", pluralErrors: "errors" }, buttons: { browse: "Browse Files", addMore: "Add More", stopUpload: "Stop Upload", cancelRemaning: "Cancel remaining Uploads", resumeUpload: "Resume Upload" }, queue: { emptyQueue: "File list: No files waiting to be uploaded.", queueSummary: "File list: %totalUploaded files uploaded, %totalInUploadQueue file waiting to be uploaded." } }
demo	Boolean indicating whether to run in "demo" mode. See Running locally: "demo" mode below.	false	`demo: false`

`queueSettings` Options

Name	Description	Values	Default

Name	Description	Values	Default
`uploadURL`	The URL to which files should be sent via POST requests.	String	""
`fileUploadLimit`	The maximum number of files allowed to be uploaded. 0 is unlimited.	Integer	0
`fileQueueLimit`	The number of files that can be queued at once before uploading them. 0 is unlimited	Integer	0
`postParams`	Parameters to send along with the POST request to the server when uploading files.	Javascript Object	{}
`fileSizeLimit`	The maximum size of a file to send to the server. Files larger than this will not be added to the queue.	Integer, specified in bytes	"20480"
`fileTypes`	The type of files that are allowed to be uploaded. Each file type should be specified as .[fluid:file extension], separated by semicolons. Example: ".jpg;.jpeg;.gif;*.tiff"	String	"." in v1.0 "*" in v1.1 `null` in v1.4

`htmlStrategy` Options

Name	Description	Values	Default

Name	Description	Values	Default
`legacyBrowserFileLimit`