Creating an Uploader

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

var myUploader = fluid.progressiveEnhanceableUploader(container, enhanceable, options);

Returns: The Uploader component object.

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.

enhanceable

The enhanceable is a CSS-based selector, single-element jQuery object, or DOM element indicating the DOM element to show if the system requirements aren't met.

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 (for more information about events in the Fluid Framework, see Events for Component Users):

Please note that there are other events that are fired by the SWFUpload object which are not used by the Fluid Uploader but that you could add a listener for.

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. Due to limitations with the Flash back-end used by Uploader, these objects should be treated as transient: as different events fire for a single file, you'll get passed a new File object each time.

File object: a representation of each file in the file queue, as provided from the upload manager.

  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
  type : string,           // The file type as reported by the client operating system
  creationdate : Date,     // The date the file was created
  modificationdate : Date, // The date the file was last modified
  filestatus : number      // The file's current status.
                           // Use fluid.uploader.fileStatusConstants to interpret the value.

Notes:

• depending on the implementation of the upload manager other values maybe present in the file object.
• the file object should be treated as read-only since it is frequently refreshed by the upload manager during the Uploader workflow.

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. Many of these constants are provided by the underlying SWFUpload library used by the Uploader, and their meaning is not specific to the Uploader.

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 uploadManager option, which allows you to choose between the fluid.swfUploadManager for use with a server, or the fluid.demoUploadManager for use locally for demos and UI development. However you could also replace the Progress subcomponent, or the File Queue subcomponent, with 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 File Queue, Progress, and swfUploadManager subcomponents. The options for swfUploadManager contain many of the settings that control which files can be uploaded to the server.

Uploader Options:

decorators: {
    type: "fluid.swfUploadSetupDecorator"
},

fileQueueView: {
    type: "fluid.fileQueueView"
},

totalProgressBar: {
    type: "fluid.progress",
    options: {
        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"
        }
    }
},

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: {
        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"
    }
}

swfUploadManager Options

demoUploadManager Options

swfUploadSetupDecorator Options

The fluid.swfUploadSetupDecorator is a small subcomponent designed to set up the DOM correctly for use by the SWFUpload library we use to power the Uploader. By default, it is turned on in the Uploader component, and you shouldn't need to turn it off. The swfUploadDecorator provides a few options that may be of interest to you in customizing the appearance of the Uploader when using it with Flash 10:

styles: {
            browseButtonOverlay: "fl-browse-button-overlay"
        }

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

Note: Please see the Progress API document for a full description of Fluid 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 InflusionAll.js file
• the Fluid layout CSS file
• the Uploader CSS file

as shown below:

<link rel="stylesheet" type="text/css" href="/framework/fss/css/fss-layout.css" />
<link rel="stylesheet" type="text/css" href="components/uploader/css/Uploader.css" />
<script type="text/javascript" src="framework/core/js/InfusionAll.js"></script>
<script type="text/javascript" src="framework/core/js/ProgressiveEnhancement.js"></script>

NOTE that the file ProgressiveEnhancement.js is not included in InfusionAll.js, and so must be included separately, even if you are using InfusionAll.js.

Alternatively, the individual file requirements are:

<link rel="stylesheet" type="text/css" href="components/uploader/css/Uploader.css"" />
<link rel="stylesheet" type="text/css" href="framework/fss/css/fss-layout.css" />

<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="lib/swfobject/js/swfobject.js"></script>
<script type="text/javascript" src="lib/swfupload/js/swfupload.js"></script>
<script type="text/javascript" src="framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="framework/core/js/ProgressiveEnhancement.js"></script>

<script type="text/javascript" src="components/progress/js/Progress.js"></script>

<script type="text/javascript" src="components/uploader/js/FileQueue.js"></script>
<script type="text/javascript" src="components/uploader/js/SWFUploadManager.js"></script>
<script type="text/javascript" src="components/uploader/js/Scroller.js"></script>
<script type="text/javascript" src="components/uploader/js/Uploader.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 compontent configuration:

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

To run locally, it is also necessary to make some minor modifications to your Flash settings in order to allow the Flash component to view files on your local machine from a locally instantiated Flash file. See Enabling Uploader on Local File Systems for instructions.