Uploader API - v0.3
This documentation refers to the v0.3 released version 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.
For a more detailed technical overview, see Uploader Design Overview.
Constructor
fluid.Uploader(uploaderSelector, uploadURL, flashURL, settings);
Parameters
uploaderSelector
The uploaderSelector
is a CSS-based selector identifying the container of the Uploader in the DOM.
uploadURL
The uploadURL
is the URL or URI of the server-side handler for the file upload.
Join the fluid-talk mailing list and ask your questions there.
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 |
---|---|---|---|
|
maximum size for each file in bytes |
|
"20480" |
|
accepted file types |
|
" |
|
user-focused short description of which files are accepted |
|
"image files" |
|
|
|
0 |
|
|
|
0 |
|
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 |
|
"" |
|
URL, URI, or function to load when the user clicks the Done button. If empty the button dismisses the dialog or reloads the page. |
|
"" |
|
URL, URI, or function to load when the user clicks the Cancel button. If empty the button dismisses the dialog or reloads the page. |
|
"" |
|
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) {} |
|
usually set by the application to identify the current context for the upload |
|
null |
|
empty selector of the HTML element to replace on the page with the File Upload UI |
|
"" |
|
automatically display a new URL or close the dialog when the upload is complete |
|
true |
|
|
milliseconds |
2000 |
|
maximum height in pixels for the file queue before scrolling |
|
190 |
|
display the upload in a DHTML dialog |
|
false |
|
indicates whether or not to automatically open the native Browse window |
|
false |
|
selector for the 'Add Files' button |
|
".fluid-add-files-btn" |
|
Javascript object containing selectors for various fragments of the uploader markup |
see "Selectors" below |
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", fileQueue: ".fluid-uploader-queue", scrollingElement: ".fluid-scoller", emptyRow : ".fluid-uploader-row-placeholder", txtTotalFiles: ".fluid-uploader-totalFiles", txtTotalBytes: ".fluid-uploader-totalBytes", osModifierKey: ".fluid-uploader-modifierKey", txtFileStatus: ".removeFile", progress : ".fluid-progress", qRowTemplate: "#queue-row-tmplt", qRowFileName: ".fileName", qRowFileSize: ".fileSize", qRowRemove: ".fileRemove", }; |
|
provides verbose debugging output both in the browser and to the console |
|
false |
Selectors
Name |
Description |
Default |
---|---|---|
|
selector of the DOM element that triggers the upload action |
".fluid-uploader-upload" |
|
|
".fluid-uploader-result" |
|
selector of the DOM element that triggers the pause action |
".fluid-uploader-pause" |
|
selector of the DOM element that triggers the browse files action |
".fluid-uploader-browse" |
|
selector of the DOM element that triggers the done action |
".fluid-uploader-done" |
|
selector of the DOM element that triggers the cancel action |
".fluid-uploader-cancel" |
|
|
".fluid-uploader-queue" |
|
|
".fluid-scroller" |
|
|
".fluid-uploader-row-placeholder" |
|
|
".fluid-uploader-totalFiles" |
|
|
".fluid-uploader-totalBytes" |
|
|
".fluid-uploader-modifierKey" |
|
|
".removeFile" |
|
|
".fluid-progress" |
|
|
"#queue-row-tmplt" |
|
|
".fileName" |
|
|
".fileSize" |
|
|
".fileRemove" |
Dependencies
Required
Fluid framework: Fluid-all.js
Optional
To present the Uploader in a DHTML dialog
jquery.dimensions.js
ui.mouse.js
ui.draggable.js
ui.resizable.js
ui.dialog.js
Files (included in the Fluid Infusion package)
Uploader.js
(included in Fluid-all.js)
Uploader.css
swfupload.js
(version 2.1.0 beta 2, included in Fluid-all.js)
swfupload_f9.swf
(version 2.1.0 beta 2)
Notes:
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. The distribution includes a ReadMe.txt
file in the sample code that provides clear instructions on how to make this change.