Fine Uploader 4.0: Image previews & templating redesign

Update 2: Oct 30, 2013 – 4.0.3 Hotfix Release

This hotfix release addresses the following issues:

  • A TypeError if an invalid container element (something other than canvas or img) is passed to the drawThumbnail API method. (#1032)
  • Drag-related errors when utilizing a custom build that excludes Fine Uploader UI but includes the drag & drop module. (#1031)

Update 2: Oct 28, 2013 – 4.0.2 Hotfix Release

This hotfix release addresses the following issues:

  • The build generator was concatenating the S3 module before the Fine Uploader UI module. Since the S3 module inherits from the UI module (when in UI Mode) this was causing an exception on page load. (#1027)
  • The upload button was being hidden by the dropzone element in Internet Explorer 7 due to its inability to check DOM node attributes which do not have values. (#1029)

Update: Oct 24, 2013 – 4.0.1 Hotfix Release

This hotfix release addresses the following issues:

  • Fine Uploader UI: User is prompted with “The files are being uploaded” alert if they attempt to navigate away from the page after cancelling an in-progress upload. (#1021)
  • Fine Uploader UI: Clicking a button next to a file with a template that nests the file template items 2 or more levels below the .qq-upload-list-selector container results in a browser lockup. (#1023)

The 4.0 release brings some big changes and features. Most notably:

Templating overhaul

Templating in Fine Uploader UI has been a bit of a mess since day one. It has been a long-standing goal of ours to fix all of the issues with the templating system and make it much easier to customize the default look and feel when using Fine Uploader UI. 4.0 brings forth the required changes to make this happen. Note that we needed to make breaking changes to address these previous shortcomings. You can read more about the breaking changes in the “Upgrading to 4.x” guide on the docs site.

The most obvious and effective change involved moving the template declaration out of the javascript file. It now must be declared in your HTML document. Also, the file template and main template are combined.

It is much more intuitive to modify HTML in an HTML file. It’s acceptable in most cases to deal with small amounts of HTML in javascript files, but the size of the template in Fine Uploader continues to grow and become more complex. Arguably, it should have never been part of the javascript file. It’s simply not proper to work with non-trivial HTML fragments in a javascript file. Manipulating a long string of HTML is frustrating and unintuitive. This becomes a bigger problem if you split the integration work of a library like Fine Uploader between a developer and a designer. In that case, the designer naturally wants to work with the HTML/CSS and leave the JS and other code to the developer.

Other issues with templating have been addressed as well. For example, it was not possible to remove an element from the template. This would cause the uploader to break. This meant that changes/additions to the template over time would cause existing apps to break if they overrode the template previously (until they updated their template, even if the new element(s) were not needed by the app). Also, Fine Uploader used the same CSS classes on each template item for both default styling and for selection internally. This made it complicated to remove or change the CSS class. All of these issues are fixed in 4.0, along with a number of other templating improvements.

If you would like to read more about templating in 4.0, please read the updated styling documentation guide.

Client-side image previews

If you use the simple-thumbnails template in your document, or simply include an appropriate <img> tag in your custom template, Fine Uploader will attempt to draw a preview of any dropped or selected files, before the upload request is even sent.

Client-side preview generation is supported in all browsers, except for Internet Explorer 9 and older. Only image files can be previewed at this time, and the types of previewable files are GIF, JPEG, BMP, PNG, and TIFF (Safari-only). Fine Uploader will even ensure JPEGs are oriented correctly by reading the Orientation tag in the EXIF header. Also, previews will be scaled according to the value of the qq-max-size attribute on the qq-thumbnail-selector <img> tag in your template.

For Fine Uploader Core users (and for Fine Uploader UI users, if desired) an API method, drawThumbnail now exists. This allows you to pass an <img> or <canvas> element, along with an optional max size parameter, and a file ID. Fine Uploader will attempt to draw a preview on the passed element for the associated file.

You can read more about this feature on the preview & thumbnails documentation page. Demos of this feature are also available on the home page.

Server-generated thumbnail display

While modern browsers allow for client-side pre-upload preview generation, this is not possible in older browsers, such as Internet Explorer 9 and older. But, we have a workable solution if you value consistence in your UI across all platforms. Simply generate a thumbnail server-side when handling the upload request and return a URL to the thumbnail in your response, via a thumbnailUrl JSON property. Fine Uploader will render this thumbnail and even automatically scale it, if desired.

This feature is also potentially useful for modern browsers if you would like to display a thumbnail for a non-image. For example, if your server is able to quickly generate an image preview for a PDF or a video file, you can return a link to this thumbnail in your upload response. Future versions of Fine Uploader may be able to generate these previews client-side as well though.

You can read more about this feature on the preview & thumbnails documentation page. Demos of this feature are also available on the home page.

More flexible callback syntax for jQuery plug-in users

You can now use the non-jQuery (traditional) callback syntax when using the jQuery plug-in or/and register jQuery event handlers for Fine Uploader’s callback events. This enhancement has been noted at the bottom of the integrating with the jQuery plug-in docs page. The traditional syntax for callbacks is demonstrated in the callbacks section of the “Getting Started Guide”.

Custom build generator

Commercial license holders may now generate a custom build of Fine Uploader (for the latest stable release) right from the home page at any time. Furthermore, you can select specific features you would like to use. Code associated with features you exclude will not be part of the combined javascript file. This will ensure the combined javascript file is no larger than it needs to be. Currently, you can select or de-select UI, direct-to-S3, upload via paste, drag & drop, image previews/thumbnails, delete file, and edit filename features via the custom build generator. More features will be added to the list over time. Any features not mentioned on the custom build generator page will always be included with all custom builds.

Other fixes & changes


As always, for up-to-date information about features and fixes planned for the next release (4.1), please see the milestone in the Github issue tracker. We will begin to plan the 4.1 release shortly after this release of 4.0.