Category Archives: 3.7

Fine Uploader 3.7 Released

UPDATE: July 24, 2013 – 3.7.1 Hotfix Release

This hotfix release addresses the following defect:

  • Cannot click “delete” or “cancel” button in UI mode when editFilename feature is enabled (#925 & #926)



The 3.7 release brings a big new feature for FineUploader mode users (Edit Filenames) along with a number of enhancements to existing features, such as the ability to send delete file requests via POST (instead of just DELETE), and cross-origin support for delete file requests.  Read on for specifics regarding all changes that went into this release, as well as information about the plans for the next release.

Features & Enhancements

Bugs Fixed

Improvements to Maintainability

Automated tests are finally being written for Fine Uploader, now that we have more resources at our disposal.  Builds are run with unit tests via Travis CI.  A set of cross-browser unit tests exist, and these tests are being run on all supported browsers via Sauce Labs.  Note that Android tests are not yet automated due to some issues with reporting, but we hope to have that addressed in the near future.  Our build tool has switched from Gradle to GruntJs, and we are embracing NodeJs and Coffeescript much more.  The next step is to write integration/workflow automated tests which will also run on all supported browsers.


We are also attempting to provide better support for our end-users via a newly redesigned documentation website.  The existing documentation has been reformatted and moved to, where you will be able to easily read documentation for current and past versions of Fine Uploader.  Documentation for the “develop” branch, where features for the next release are being staged, will also be accessible.

List Your Site on

Are you using Fine Uploader in your web application?  Do you want your site listed on  If so, let us know by sending an email to  We are currently compiling a list of such sites, and have plans to create a section on to display screenshots and other information about apps that utilize Fine Uploader.

What’s Up Next?

3.8 will focus primarily on allowing you to easily upload files directly to Amazon S3, bypassing your origin server.  The plan is to support all existing Fine Uploader features in all browsers when dealing with S3.  Some server-side intervention will be required (such as to sign requests before they are sent to S3), but this integration is valuable as it ensures the file bytes are sent directly to S3, saving bandwidth and cutting out the middleman (your server).

You can track (and comment on) progress on the S3 feature by tracking the following features in the Github repo:

Let us know if we can do anything to improve your uploading experience!

– Ray Nicholus, Mark Feltner, and the rest of the team @ Widen

3.7: Edit / Override File names

Fine Uploader version 3.7 brings a brand new feature targeting FineUploader mode: the ability to edit a submitted file or blob’s name. 3.7 brings a new API method for FineUploaderBasic mode users who want to utilize the convention put in place for overriding a filename while providing their own UI. FineUploader mode users get support for this new feature baked into the provided UI. Note that, in both cases, the feature only makes sense when the autoUpload option is set to false. If autoUpload is set to true (the default value), this feature will be disabled in FineUploader mode.

Turning on the edit filename feature in FineUploader mode

In order to enable this feature, you must set the enabled property of the new editFilename option. Also, as stated earlier, the autoUpload option must be set to false. Here’s a very simple example:

    autoUpload: false,
    request: {
        endpoint: 'my/endpoint'
    editFilename: {
        enabled: true

Editing a file name

When this feature is properly enabled, you will notice an edit icon next to each submitted file in the UI, assuming the filename is editable at the time. Also, notice the cursor will be set to “pointer” in this case. A filename is editable only while the upload status is SUBMITTED. This means that you may edit your file after submitting it, before calling the uploadStoredFiles API method.

When an editable file name is clicked/touched, a text input will appear. Here, the filename can be changed. Note that the extension is not modifiable. The original extension will always be appended to the filename after the name edit is complete. The extension is not editable to ensure that any validation rules surrounding file type are not violated.

After editing a filename, you have a few options:

  • Press ENTER to save the change.
  • Click or touch some other area on the page to save the change.
  • Hit TAB to edit the name of the next file in the UI (and save the name entered into the current input box).

Note that an empty file name is not an acceptable value. In this case, the original or previously overridden file name will be used instead.


By default, Fine Uploader places an edit icon next to each editable file name (only) when it is editable. The cursor is changed to a pointer when it is over the file name or the edit icon (only) when the file name is editable. Finally, the file name element is hidden and a text input element is displayed when the file name or edit icon is clicked/touched/focused. The following associated properties have been added to the classes option:

  • editFilenameInput: attached to the text input element
  • editNameIcon: Attached to the element holding the edit icon
  • editable: Attached to the icon or input when the associated file name is editable

The fileTemplate option has changed to allow for these new elements as well. UPDATE: Templating changed drastically in Fine Uploader 4.0. If you are using 4.0, please read the styling documentation page for details.

Things to be aware of

When a file name has been modified, please keep the following in mind:

  • Fine Uploader cannot change the filename listed in the header of the associated file’s multipart boundary. The new file name is sent as a parameter along with the request. See the server-side section below for more details.
  • The getUploads API method can be used to obtain the original file name. All objects returned by this method will now include an originalName property. The name property will be set to the current file name.
  • The getName API method will return the current file name, not the original file name.
  • All name parameters passed to callback handlers will equal the new file name, not the original file name.
  • The resume feature will key on the most current (not necessarily the original) file name when deciding if a submitted file is resumable. This determination is made by Fine Uploader just before the first upload request for the file request is sent. If you submit a previously interrupted file with an overridden name, you must ensure the file name is again changed to ensure the file is properly resumed.

Handling an overridden / new file name server-side

If a file name has been edited / overridden client-side, a “qqfilename” parameter with the new file name will be included with the upload request. If you see this parameter in the request, you should use the associated value when naming your file and not the value of the filename parameter of the Content-Disposition header associated with the file’s multipart boundary. Note that the “qqfilename” parameter is named by default, but is also tied to the new filenameParam property of the request option. This change is associated with some other breaking changes. See the breaking changes section below for more details.

Breaking changes

All breaking changes are related to cleanup of filename-related parameters passed along with the requests. These breaking changes don’t represent a complete cleanup of this mess, but this gets most of the job done.
All breaking changes are related to cleanup of filename-related parameters passed along with the requests. These breaking changes don’t represent a complete cleanup of this mess, but this gets most of the job done.

  • The name property of the blobs.paramNames option has been removed. The new filenameParam property of the request option replaces this.
  • The fileName property of the chunking.paramsNames option has been removed. The new filenameParam property of the request option replaces this.

3.7: Cross-Origin Delete File Support for IE9 and IE8

Previously, support for the delete file feature for cross-origin environments excluded IE9 and older as these browsers
do not support cross-origin requests via XMLHttpRequest, among other restrictions. IE9 and IE8 are now supported as of 3.7, however IE7 is not due to the lack of any XMLHttpRequest-like CORS support in this version of Internet Explorer. Theoretically, this could be accomplished by making use of a hidden iframe, as is currently done to support file upload request in IE9 and older, but this would add yet another layer of complexity to the code for the delete file feature and it is not clear that the low IE7 market share merits this additional complexity.

If you do not want to enable cross-origin delete file requests in IE9 and IE8, simply ensure the allowXdr property of the cors option is set to false. This is the default value of this property.


As of Fine Uploader 3.7, you may optionally enable support for the delete file feature in IE9 and IE8 for cross-origin environments, provided you:

var uploader = new qq.FineUploader({
  element: document.getElementById("myFineUploader"),
  request: {
    endpoint: 'my/endpoint'
  cors: {
    expected: true,
    allowXdr: true
  deleteFile: {
    enabled: true,
    method: 'POST'

Support for the delete file feature in cross-origin environment in IE9 and IE8 is disabled, by default, due to the limitations that come along with use of IE’s XDomainRequest If you elect to enable this type of support, you will need to adjust your server code appropriately and be aware of the limitations associated with XDomainRequest.

Limitations of delete file requests in IE9 and IE8 (XDomainRequest)

While 3.7 now provides support for the delete file feature in IE9 and IE8, this enhancement is not without its own limitations, thanks to Internet Explorer’s XDomainRequest. XDomainRequest is one of many examples of Microsoft creating proprietary short-sighted standards in IE. We are forced to use XDomainRequest in IE9 and IE8 if we want to send cross-origin ajax requests. Keep in mind that XDomainRequest comes with the following limitations in the context of the delete file feature:

  • You may not send any custom headers. This means that the customHeaders property of the deleteFile option will be ignored in cross-origin environments when the user agent is IE9 or IE8.
  • Only POST requests may be sent. Technically, XDomainRequest allows you to use GET as well, but that isn’t an appropriate method for deleting a file, so Fine Uploader won’t allow this. So, you must set the method property of the deleteFile option to “POST”. See the Fine Uploader blog post on using the POST method to send delete file requests for more details.
  • The Content-Type of the request cannot be defined. XDomainRequest does not permit you to set any custom headers, and, as a result, you will find that the Content-Type header is absent from the request when you attempt to parse it server-side. This will likely require additional server-side code to parse POST requests with a missing Content-Type header.
  • Credentials (cookies) will not be sent with the request. This means that the sendCredentials property of the cors option will be ignored in IE9 and IE8 for all cross-origin delete file requests.

Handling delete file requests in IE9 and IE8 server-side

The java example has already been modified to handle delete file cross-origin requests sent by XDomainRequest. Have a look at the RequestParser class for implementation details. Other server-side examples will be modified in the near future to handle these requests. In the meantime, please read on if you would like to modify your own server-side code.

Since IE will not send a Content-Type header with any XDomainRequests (as noted above), many server-side libraries/frameworks will not parse the contents of a POST request sent via XDomainRequest. This means that you will need to do one of two things:

  • “Trick” whatever library or framework you are using into thinking that the request has a Content-Type header of “application/x-www-form-urlencoded”. This may be easy or quite difficult, depending on the framework/library. If it is possible though, this may be enough to handle XDR POST requests.
  • Failing faking out whatever library you are using to parse requests, you will need to write your own code to parse URL encoded POST request payloads. More specifically, you will need to include some logic in your server-side code that equates realizes POST requests from Fine Uploader without Content-Type headers actually contain URL encoded payloads. This code will need to parse the payload into parameters. This really shouldn’t be very difficult, but it is a bit of an annoyance.

Preflighting can now be avoided

One additional benefit provided here is the ability to ensure cross-origin delete file requests are not preflighted. Remember that preflighting was discussed in the initial CORS support blog post, and, before this enhancement, all delete file requests sent by Fine Uploader were preflighted. Now, you can avoid preflighting entirely for delete file requests simply by setting the method property of the deleteFile option to “POST”. While this change is required for IE9 and IE8 support of the delete file feature for cross-origin environments, you do not need to allow XDR requests (enable support in IE9/IE8) to prevent preflighting in other browsers.

Happy Uploading!

– Ray Nicholus and the rest of Widen

Delete files via POST and DELETE requests

Updates since the original post/feature implementation

In Fine Uploader 3.3, the ability to easily delete uploaded files was added as a new feature. At that time, all associated delete file requests sent by the library were DELETE requests only. While this is the most appropriate verb to use when performing this type of action, it became clear that some users are not able to handle DELETE requests server-side due to restrictions placed on firewalls/appliances/servers that are beyond their control. So, in Fine Uploader 3.7, you will now be able to choose between DELETE or POST as the method type for these delete file requests.

A new property of the deleteFile option has been added: method. method has two valid values: “DELETE” and “POST”.

If you choose “DELETE”, all delete file requests will be sent using a DELETE request, with the file UUID at the end of the URI and any additional parameters URL encoded in the query string. You can read more about deleting files with the DELETE request in the original delete file feature blog post. This is the only way the delete file feature has sent requests until now.

If you choose “POST”, all delete file requests will be sent using a POST request, with the file UUID sent as a (by default) “qquuid” parameter along with a “_method” parameter sent with a value of “DELETE”. The “_method” parameter is named as such as this seems to be a commonly accepted convention, according to RESTful Web Services, among other sources such as discussions on Stackoverflow. Also please note that all parameters for this POST request are sent, URL encoded, in the request payload, which is also commonly accepted. Valid status codes for this POST request are 200 and 204, per the HTTP spec. Please also note that the name of the “qquuid” parameter is configurable via the uuidName property of the request option.

Other than that, everything is about the same with the delete file feature. Again, see the original blog post on this feature if you require a refresher, but keep the new method property in mind.

Happy Uploading!

Ray Nicholus and the rest of Widen