This page has not yet been updated to reflect the latest API changes.
The Infusion Uploader provides an easy way for users to upload many files at once, providing useful feedback about the status and progress of each file along the way.
Uploader implements a couple different ways to upload multiple files. With its built-in support for progressive enhancement, users will automatically receive a version of the Uploader best suited to the capabilities of their browsers. There are two different flavours of Uploader:
The HTML 5 version of the Uploader will be delivered to modern, standards-compliant browsers, including:
NOTE: As of Infusion 1.5, the Flash version of the Uploader has been removed due to a cross-site scripting vulnerability.
The Infusion Uploader, like many Fluid components, is really one interface to a collection of components that work together to provide a unified user experience.
The Uploader provides a facade object, called a
strategy, which represents the entire subsystem for a particular implementation of Uploader. There are currently two different strategies available to choose from:
fluid.uploader.html5Strategy, which provides the modern HTML 5 implementation of Uploader
fluid.uploader.progressiveStrategy, which uses the new Infusion IoC - Inversion of Control System to deliver the best possible version of Uploader based on the capabilities of the user's browser.
The default strategy for Uploader is
Upgrading from Infusion 1.2: The Uploader was substantially refactored for the Infusion 1.3 in order to support the new HTML 5 version. However, most users should be unaffected. All events, selectors, and classes remain compatible with previous versions. Since the Uploader's underlying structure has changed significantly, and support for Infusion's IoC System was introduced, several other configuration options have changed.
In order to ease the transition, we've provided a compatibility file that will automatically transform your options from the old format to the new when you invoke
fluid.uploader(). This can be enabled simply by including the
UploaderCompatibility-Infusion1.2.js file your page. If you're not using a custom build of Infusion, you will also need to include the framework's
To instantiate a new Uploader on your page using the recommended progressive enhancement feature:
Returns: An Uploader component object. The resulting type may be either
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.
container is a CSS-based selector, single-element jQuery object, or DOM element that identifies the root DOM node of the Uploader markup.
options object is an optional data structure that configures the Uploader, as described in the fluid:Options section below.
The Uploader fires the following events (for more information about events in the Fluid Framework, see Events for Component Users):
The event is fired when the OS File Open dialog is displayed.
The event is fired when files have been selected for addition to the file queue.
The number of files selected.
This event is fired for each file that is queued after the File Selection Dialog window is closed.
Event is fired for each file that is removed from the filequeue model
This event is fired for each file that was not queued after the File Selection Dialog window is closed.
This event fires after the File Selection Dialog window has been closed and all the selected files have been processed.
This event at the beginning of the entire upload cycle.
This event is fired immediately before the file is uploaded.
This event is fired periodically by the upload manager during a file upload and is useful for providing UI updates on the page.
This event is fired any time an individual file upload is interrupted or does not complete successfully.
This event is fired when an upload completes and the server returns a HTTP 200 status code.
This event is fired for each file uploaded whether or not the file is uploaded successfully (
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.
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.
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
An HTTP error occurred while uploading a file.
An IO error occurred while transferring the file.
The upload caused a security error to occur.
The user attempted to upload more files than allowed by the
The Uploader was unable to start uploading the file to the server
This indicates an error in the Uploader and should be filed as a bug
The upload was canceled by the user.
The upload was stopped by the user.
File Status Constants
The file is currently queued up and ready to be sent to the server.
The file is currently being uploaded to the server.
An error occurred while trying to upload the file.
The file was successfully uploaded to the server.
The file was canceled by the user while in the process of being uploaded.
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 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
The strategy for how files are uploaded to the server (e.g. HTML 5, etc.)
Specifies the type of fileQueueView subcomponent to use.
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.
see #Selectors below
Keys in the object are event names, values are functions or arrays of functions.
Keys in the object are supported event names.
Specific class names used to achieve the look and feel of the different states of the Uploader
Strings that are used in the Uploader.
Boolean indicating whether to run in "demo" mode. See Running locally: "demo" mode below.
The URL to which files should be sent via POST requests.
The maximum number of files allowed to be uploaded. 0 is unlimited.
The number of files that can be queued at once before uploading them. 0 is unlimited
Parameters to send along with the POST request to the server when uploading files.
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
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"
"*.*" in v1.0
A special file size limit for older browsers (such as Firefox 3.6), which don't fully support HTML 5 file uploads.
any integer value, specified in megabytes
The different parts of the Uploader interface each have their own set of selectors (though all selectors must be provided together in a single object). Each also has a default, as defined below:
The container element of the File Queue.
The Browse Files button.
The Upload button.
The Pause button.
The file container for the total progress bar.
The element to write the total progress bar status text into.
The element containing the browse files instructions.
The files rows in the queue.
The container for the file's name. Scoped within an individual file row.
The container for the file's size. Scoped within an individual file row.
The container for the file row icons. Scoped within an individual file row.
The container for file specific error text. Scoped within an individual file row.
A template element to clone when creating new rows in the file queue.
A template element to close when displaying an error for an individual file.
A template element to clone when creating the progress bar for a file row.
A wrapper container around the scrollable element.
Note: Please see the Progress API document for a full description of Fluid Progress. Uploader uses the following selector options for Progress:
Any selectors not provided as an option will revert to the default. Implementers may choose to use the default class names in their markup, or customize the selectors, or a combination of these two approaches.
For example, if your markup uses all of the default selectors, except for the file queue selector and the remove button selector, you would provide the following selectors option:
The Uploader dependencies can be met by including in the header of the HTML file
as shown below:
Alternatively, the individual file requirements are:
The Upload component requires a server component to accept the uploaded files.
However there are times when you want to run the uploader with out a server: when working on integrating the component with your code, developing or testing the UI, or demonstrating the functionality of the code. For that reason the Uploader has a "demo" mode. In demo mode, the Uploader uses a special version of the uploadManager that pretends to be talking to a server. Most of the code is identical to the server mode because the same events are being fired and the model is exactly the same. Most of the code in the Uploader thinks that there is a server.
To run locally you must specify
demo: true in your compontent configuration: