Uploader API

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:

1. Single file: delivered to browsers that don't support JavaScript and HTML 5
2. HTML 5: the best and most widely-supported version of Uploader, suitable for modern browsers

The HTML 5 version of the Uploader will be delivered to modern, standards-compliant browsers, including:

• Internet Explorer 10+
• Firefox 3.6+
• Safari 4+
• Google Chrome

Progressive Enhancement

The Uploader utilizes the concept of progressive enhancement. The goal is to ensure that the page is usable by the widest possible audience, even with old browsers or when JavaScript is turned off. This is done by specifying a regular file input element in the markup. When the Uploader is initialized, the Upload code will replace that element with the Fluid Uploader. As of Infusion 1.3, progressive enhancement will occur automatically by default. It can be overridden by choosing a specific upload strategy instead of using the fluid.uploader.progressiveStrategy.

Upload Strategy

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:

1. fluid.uploader.html5Strategy, which provides the modern HTML 5 implementation of Uploader
2. fluid.uploader.progressiveStrategy, which uses the 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 fluid.uploader.progressiveStrategy.

Upgrading

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 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 ModelTransformations.js file.

Creating an Uploader

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

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

Returns: An 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 Options section below.

Supported Events

The Uploader fires the following events

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 File object.

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 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

strategy: {
    type: "fluid.uploader.progressiveStrategy"
}
                

fileQueueView: {
    type: "fluid.fileQueueView"
}
                

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

focusWithEvent: {
    afterFileDialog: "uploadButton",
    afterUploadStart: "pauseButton",
    afterUploadStop: "uploadButton"
},
                

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: {
    progress: {
        fileUploadLimitLabel: "%fileUploadLimit %fileLabel maximum",
        noFiles: "0 files",
        toUploadLabel: "%uploadedCount out of %totalCount files uploaded (%uploadedSize of %totalSize)",
        totalProgressLabel: "%uploadedCount out of %totalCount files uploaded (%uploadedSize of %totalSize)",
        completedLabel: "%uploadedCount out of %totalCount files uploaded (%uploadedSize of %totalSize)%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",
        remove: "Remove"
    }
}
                

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."
    }
}
                

queueSettings Options

htmlStrategy Options

Selectors

One of the options that can be provided to the Uploader is a set of CSS-based selectors identifying where in the DOM different elements can be found. The value for the option is itself a Javascript object containing name/value pairs:

{
    selectors: {
        selector1Name: "selector 1 string",
        selector2Name: "selector 2 string"
        // ...
    }
}

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:

General

File Queue

Scroller

Progress

Uploader uses the following selector options for Progress:

{
    selectors: {
        progressBar: ".flc-uploader-queue-footer",
        displayElement: ".flc-uploader-total-progress",
        label: ".flc-uploader-total-progress-text",
        indicator: ".flc-uploader-total-progress",
        ariaElement: ".flc-uploader-total-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:

{
    selectors: {
        fileQueue: "#my-file-queue",
        removeButton: "#my-remove-button"
    }
}

Dependencies

Required

The Uploader dependencies can be met by including in the header of the HTML file

• the minified infusion-all.js file
• the Fluid layout CSS file
• the Uploader CSS file

as shown below:

<link rel="stylesheet" type="text/css" href="/framework/core/css/fluid.css" />
<link rel="stylesheet" type="text/css" href="components/uploader/css/Uploader.css" />
<script type="text/javascript" src="framework/core/js/infusion-all.js"></script>

Alternatively, the individual file requirements are:

<link rel="stylesheet" type="text/css" href="../../../framework/core/css/fluid.css" />
<link rel="stylesheet" type="text/css" href="../css/Uploader.css" />

<!-- Fluid and jQuery Dependencies -->
<script type="text/javascript" src="../../../lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="../../../lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="../../../framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="../../../framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="../../../framework/core/js/FluidDocument.js"></script>
<script type="text/javascript" src="../../../framework/core/js/FluidView.js"></script>
<script type="text/javascript" src="../../../framework/core/js/DataBinding.js"></script>
<script type="text/javascript" src="../../../framework/core/js/FluidIoC.js"></script>
<script type="text/javascript" src="../../../framework/enhancement/js/ProgressiveEnhancement.js"></script>

<!-- Uploader dependencies -->
<script type="text/javascript" src="../js/Uploader.js"></script>
<script type="text/javascript" src="../js/FileQueue.js"></script>
<script type="text/javascript" src="../js/Scroller.js"></script>
<script type="text/javascript" src="../../progress/js/Progress.js"></script>
<script type="text/javascript" src="../js/FileQueueView.js"></script>
<script type="text/javascript" src="../js/HTML5UploaderSupport.js"></script>
<script type="text/javascript" src="../js/DemoUploadManager.js"></script>

Important Notes for Developers

Running locally: "demo" mode

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 component configuration:

var myUploader = fluid.progressiveEnhanceableUploader(".flc-uploader", ".fl-ProgEnhance-basic", {
    demo: true
});