Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Uploader API - v0.5

This documentation refers to version 0.5 of the Uploader code. For documentation specific to trunk, please see Uploader API.

Uploader Overview

The Fluid Uploader uses an approach to browser-based file uploading used by Flickr and the YUI library. This technique uses a small Flash object, with no user-interface of its own, to call a standard OS file open dialog that allows the user to select multiple files, and then uses the same Flash object to manage the interaction with the server to provide good progress feedback to the user during the file upload.

NOTE: If you will be testing the Uploader on a local file system, please see the #Important Notes for Developers below.

For a more detailed technical overview, see Uploader Design Overview.


Constructor

fluid.Uploader(uploaderContainerId, uploadURL, flashURL, settings);

Parameters

uploaderContainerId

The uploaderContainerId parameter is the ID of the root DOM node of the Uploader markup.

uploadURL

The uploadURL is the URL or URI of the server-side handler for the file upload.

flashURL

The flashURL is the URL or URI of the swfupload.swf file.

settings

The settings object is an optional collection of name-value pairs that configure the Uploader:

Name

Description

Values

Default

fileSizeLimit

maximum size for each file in bytes

 

"20480"

fileTypes

accepted file types

 

"*.*" // any file

fileTypesText

user-focused short description of which files are accepted

 

"image files"

fileUploadLimit

Defines the number of files allowed to be uploaded by SWFUpload. This setting also sets the upper bound of the file_queue_limit setting. Once the user has uploaded or queued the maximum number of files she will no longer be able to queue additional files. Only successful uploads (uploads the trigger the uploadSuccess event) are counted toward the upload limit. The setStats function can be used to modify the number of successful uploads. Note: This value is not tracked across pages and is reset when a page is refreshed. File quotas should be managed by the web server.

number

0 (no limit)

fileQueueLimit

Defines the number of unprocessed files allowed to be simultaneously queued. Once a file is uploaded, errored, or cancelled a new files can be queued in its place until the queue limit has been reached. If the upload limit (or remaining uploads allowed) is less than the queue limit then then lower number is used.

number

0 (no limit)

elmUploaderControl

selector, or HTML that is the replacement element for httpUploadElm. In the case of using the Uploader in a dialog this is probably an element that contains an Add Files link or button

 

""

whenDone

URL, URI, or function to load when the user clicks the Done button. If empty the button dismisses the dialog or reloads the page.

 

""

whenCancel

URL, URI, or function to load when the user clicks the Cancel button. If empty the button dismisses the dialog or reloads the page.

 

""

whenFileUploaded

Function to call when the server reports a successful file upload. Passes two arguments, the client-side filename and the server response. This gives application-specific client code a way to coordinate with application-specific server code, so that, for example, a set of newly uploaded resource IDs can be passed to another page, or thumbnails of newly uploaded files can be displayed in another panel.

 

function(fileName, serverResponse) {}

postParams

usually set by the application to identify the current context for the upload

 

null

httpUploadElm

empty selector of the HTML element to replace on the page with the File Upload UI

 

""

continueAfterUpload

automatically display a new URL or close the dialog when the upload is complete

 

true

continueDelay

 

milliseconds

2000

queueListMaxHeight

maximum height in pixels for the file queue before scrolling

 

190

dialogDisplay

display the upload in a DHTML dialog

 

false

browseOnInit

indicates whether or not to automatically open the native Browse window

 

false

addFilesBtn

selector for the 'Add Files' button

 

".fluid-add-files-btn"

fragmentSelectors

Javascript object containing selectors for various fragments of the uploader markup

see #Selectors below

see #Selectors below

debug

provides verbose debugging output both in the browser and to the console

 

false


Selectors

The fragmentSelectors settings object is a Javascript object containing selectors for various fragments of the uploader markup. The default is:

var defaultSelectors = {
    upload: ".fluid-uploader-upload",
    resume: ".fluid-uploader-resume",
    pause: ".fluid-uploader-pause",
    done: ".fluid-uploader-done",
    cancel: ".fluid-uploader-cancel",
    browse: ".fluid-uploader-browse",
    fluidUploader: ".fluid-uploader-queue-wrapper",
    fileQueue: ".fluid-uploader-queue",
    scrollingElement: ".fluid-scroller",
    emptyRow : ".fluid-uploader-row-placeholder",
    txtTotalFiles: ".fluid-uploader-totalFiles",
    txtTotalBytes: ".fluid-uploader-totalBytes",
    txtTotalFilesUploaded : ".fluid-uploader-num-uploaded",
    txtTotalBytesUploaded : ".fluid-uploader-bytes-uploaded",
    osModifierKey: ".fluid-uploader-modifierKey",
    txtFileStatus: ".removeFile",
    uploaderFooter : '.fluid-scroller-table-foot',
    qRowTemplate: '#queue-row-tmplt',
    qRowFileName: '.fileName',
    qRowFileSize: '.fileSize',
    qRowRemove: '.fileRemove',
    fileProgressor: '.file-progress',
    fileProgressText: ".file-progress-text",
    totalProgressor: '.total-progress',
    totalProgressText: ".fluid-scroller-table-foot .footer-total"
};

The following table describes the selectors:

Name

Description

Default

upload

selector of the DOM element that triggers the upload action

".fluid-uploader-upload"

resume

 

".fluid-uploader-result"

pause

selector of the DOM element that triggers the pause action

".fluid-uploader-pause"

browse

selector of the DOM element that triggers the browse files action

".fluid-uploader-browse"

done

selector of the DOM element that triggers the done action

".fluid-uploader-done"

cancel

selector of the DOM element that triggers the cancel action

".fluid-uploader-cancel"

fluidUploader

 

".fluid-uploader-queue-wrapper"

fileQueue

 

".fluid-uploader-queue"

scrollingElement

 

".fluid-scroller"

emptyRow

 

".fluid-uploader-row-placeholder"

txtTotalFiles

 

".fluid-uploader-totalFiles"

txtTotalBytes

 

".fluid-uploader-totalBytes"

txtTotalFilesUploaded

 

".fluid-uploader-num-uploaded"

txtTotalBytesUploaded

 

".fluid-uploader-bytes-uploaded"

osModifierKey

 

".fluid-uploader-modifierKey"

txtFileStatus

 

".removeFile"

uploaderFooter

 

".fluid-scroller-table-foot"

qRowTemplate

 

"#queue-row-tmplt"

qRowFileName

 

".fileName"

qRowFileSize

 

".fileSize"

qRowRemove

 

".fileRemove"

fileProgressor

 

".file-progress"

fileProgressText

 

".file-progress-text"

totalProgressor

 

".total-progress"

totalProgressText

 

".fluid-scroller-table-foot .footer-total"


Dependencies

Required

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

  • the minified Fluid-all.js file
  • the Fluid Infusion theme CSS file
  • the Uploader CSS file

as shown below:

<link rel="stylesheet" type="text/css" href="css/infusion-theme.css" />
<link rel="stylesheet" type="text/css" href="css/Uploader.css" />
<script type="text/javascript" src="js/Fluid-all.js"></script>

Alternatively, the individual file requirements are:

<link rel="stylesheet" type="text/css" href="css/infusion-theme.css" />
<link rel="stylesheet" type="text/css" href="css/Uploader.css" />
<script type="text/javascript" src="js/jquery/jquery-1.2.6.js"></script>
<script type="text/javascript" src="js/jquery/jARIA.js"></script>
<script type="text/javascript" src="js/jquery/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="swfupload/swfupload.js"></script>
<script type="text/javascript" src="js/fluid/Fluid.js"></script>
<script type="text/javascript" src="js/fluid/Uploader.js"></script>

Optional

To present the Uploader in a DHTML dialog, the Fluid-all.js will suffice, alternatively, the individual file requirements are:

<link rel="stylesheet" type="text/css" href="css/infusion-theme.css" />
<link rel="stylesheet" type="text/css" href="css/Uploader.css" />
<script type="text/javascript" src="js/jquery/jquery-1.2.6.js"></script>
<script type="text/javascript" src="js/jquery/jARIA.js"></script>
<script type="text/javascript" src="js/jquery/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="js/jquery/ui.core.js"></script>
<script type="text/javascript" src="js/jquery/ui.dialog.js"></script>
<script type="text/javascript" src="js/swfupload/swfupload.js"></script>
<script type="text/javascript" src="js/fluid/Fluid.js"></script>
<script type="text/javascript" src="js/fluid/Uploader.js"></script>

Important Notes for Developers

Running locally

The Upload component requires a server component to accept the uploaded files.

For testing purposes there are a set of fake upload handlers for testing the UI of the uploader in a local situation. These handlers use as much of the actual code as possible so as to be a fair test. Currently these handlers are invoked by not specifying an uploadUrl. It may make sense to remove these handlers in the release version of the component.

To run locally, it is also necessary to make some minor modifications to your Flash settings in order to allow the Flash component to run with out a server. See Enabling Uploader on Local File Systems for instructions.