type: widget

release: N/A

priority: none

status: in planning

documentation: N/A

demo: LABS

1 - Description:

A file uploader extends the default single file browse tool with to allow for a custom UI for providing feedback, the ability to upload multiple files at once and a real-time progress bar for upload feedback.

A few jQuery plugins provide all or some of this functionality:

https://github.com/blueimp/jQuery-File-Upload (demo: http://aquantum-demo.appspot.com/file-upload)

http://plugins.jquery.com/project/MultiFile/

http://www.fyneworks.com/jquery/multiple-file-upload/

http://15daysofjquery.com/multiple-file-upload-magic-with-unobtrusive-javascript/17/

http://jquery.webunity.nl/jQuery.uploader/landing (this is the latest version of the plugin that was documented on the jQuery site at http://docs.jquery.com/UI/Uploader)

http://blogs.bigfish.tv/adam/2009/06/14/swfupload-jquery-plugin/

http://www.alexandremagno.net/blogs/jqswfupload/

http://www.uploadify.com/

http://www.plupload.com/index.php Has a jQuery widget, drag and drop support, multiple file upload and more.

http://plugins.jquery.com/project/fileinput - jQuery UI widget replacement for form file inputs. Works with ThemeBuilder and custom styling.

https://github.com/blueimp/jQuery-File-Upload (demo: http://aquantum-demo.appspot.com/file-upload )

2 - Visual Design:

3 - Functional Specifications/Requirements:

All functionalities need to work independent to each other

• File input or Form replacement
• this should be the basic functionality
• Ajax
•  upload file ( or files ) without leaving the page
• Queue 
• provide an option so that a user could select multiple files and upload them at once
• Transporter
• provide different ways to allow controlled uploading

How to achieve the functionalities

File input replacement

This should be optional, the user may use any object as a uploader ( images, links etc ). Since we can't trigger a click event for a file input we have to improvise. We need to create a file input right near the selector, because the file input might be used in a form. The thing that all the plugins have in common is that it creates a file input at the cursor's position when it hovers the element. 

This is pretty easily, we must get the object's coordinates ( offset left, offset top, width and height ) and when the event meets the conditions display the file input. But we must be careful because the button may change it's position or dimension. So it's better to take in consideration a method that would recalculate the coordinates based on the current position and dimension.

Form replacement

A serious webdeveloper must, at lest, consider graceful degradation methods to ensure the accessibility of a website. As we are proposing, the jQueryUI FileUploader will do all the work alone. It is not the same as an input element, it is a powered form element!

Converting a form into a FileUploader we get some useful information about the application, we may use the non file input fields as a template to collect meta-data for each file, and if something fails the user still can to upload his files.

For each selected file a box with it's name will be created, based on the default uploader template or other provide by the user in fileBoxTemplate option. If the option autoUpload is false, all form fields, but the input file and the submit, will be cloned inside the box to be filled before the uploading start. That data will be sent in a "multipart/form-data" form with the file. If the option autoUpload is true, the form will be cloned with a hidden field named with the uploadIdFieldName option value. That will add the uploadIdFieldName with uploadId as value on the multipart-form when uploading the file (without user interaction) and the same on the meta-data form as a hidden input, to be sent when the user fill the fields and press a "save" button. That will enable the server application to recognize the relation between the uploaded file and the meta-data received on different submissions. The meta-data added by the extra fields will be visible on the metaData attribute of the FileToUpload object while it exists, independent of the autoUpload is value. All data attached on metaData attribute will be sent, so the page code may add more informations there without need a new the form field.

Ajax

The user must not need to be redirected to submit files, that allows to collect meta-data from the files while uploading, or use the FileUploader when is needed to attach files to a article being created. Examples to illustrate:

• Youtube video uploader: allows the user to send how many videos that wants and open a meta-data form to describe each uploading video.
• General article publisher: while writing the user may want to add some pictures to the article, he may click on add files on the side-box and automatically receive the published image reference (to add to the rich text editor) when the upload is ended.

Queue

The FileUploader may work with autoUpload enabled or not. autoUpload enable means that will automatically start the file upload when the user select it. In the other end, the method send() must be called. In both cases we'll have a "upload list" a list of FileToUpload objects, where each one refers to a selected file, and that order is the same as the user selection order, but may be changed as any array. The list will let to easily handle the selected files, to upload each file in a different connection, to a better progress control and to easily add some meta-data. The FileUploader will always respect the "upload list" order to build a queue, but will try to send the files in parallel, the next file must not to wait the finish of the precursor to be sent.

Transporters

• Flash 
  Allows to track the progress on old browsers (must be supported?) 
  

• XMLHttpRequest

  Must be the default transporter

• IFrame

  For old browsers without XMLHttpRequest with FormData support

API Interface

Options

• disabled - Boolean - default: false
• submitURL - String - if undefined, tries to get the form's "action" attribute.
• submitMethod - String - if undefined, tries to get the form's "method" attribute.
• maxFiles - Integer - default: 0 means no limit on the number of selected files to upload
• maxFileSize - KB in Float - default: 0 means no limit per selected file
• maxTotalFileSize - KB in Float - default: 0 means no limit for the sum of selected files
• mimeTypes - Array of Strings - default null (define a list of accepted file types to upload)
• fileBoxTemplate - jQuery.template reference - a default template is defined by the FileUploader
• autoUpload - Boolean - default: false (if true start uploading when the file is selected)
• uploadIdFieldName - string - default: "uploadid"
• globalProgressbar - element reference - default: null (if referenced and not converted to jQueryUI Progressbar, that may be done using default values. if defined that must be auto updated by the fileuploader, if not this fileuploader will not have a progressbar)
• showEachFile - Boolean - default: true (will show the name, progress and cancel button for each file)
• palallelLimit - Integer - default: 5 - The other files on the upload list still on queue until no one finishes. This will help to not explode the server connections when uploading several files.

Methods

• option - .fileuploader( "option" , optionName , [value] )
• addFile - .fileuploader( "addFile" , fileName , fileData ) - useful to save work done on the web using canvas or another bowser technology. Must support base64 as fileData.
• listFiles - .fileuploader( "listFiles" ) - return an array of FileToUpload objects.
• send - .fileuploader( "send" ) - start to upload all files in the upload list if autoUpload is false.

Events

• progress( total, uploaded ) - the global upload progress
• fileAdded( FileToUpload ) - with "showEachFile = false" allow to create an unique UI for each uploading file, or allow to verify file details before the upload.
• fileRemoved( uploadId, fileName )
• started()
• complited( serverResponse )
• failed( error )

The FileToUpload object

attributes:

• uploadId - String (a hash to identify the file when that must be refereed on future submitting)
• fileName - String
• fileData
• fileSize - KB in Float.
• progress - Float inside [0, 1] range.
• progressElement - jQueryUI widget reference, if there is one.
• widget - the jQueryUI fileuploader widget reference, were that file was added.
• metaData - a hash of data related to the file, to be sent as "multipart/form-data".

methods:

• send() - upload the file to the server.
• destroy() - remove the file from the uploat list.

events:

• destroying() - trigged before the FileToUpload object remotion from list. Returning false cancels the destruction.
• progress( total, uploaded ) - the file upload progress
• started()
• complited( serverResponse )
• failed( error )

4 - Markup & Style:

     4.1 Initial markup examples

     (Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )

     4.2 Recommended transformed HTML markup

     (The HTML markup structure and classes that will be used by the scripts in the enhanced version) 

     4.3 Accessibility recommendation

    (Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

     4.4 CSS & Theme

    (Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

5 - Latest version of plugin:

(Link to the latest version in the jQuery UI trunk here)

6 - Open issues being discussed

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)