The 4.0 version brings some breaking changes, mostly surrounding templating in Fine Uploader UI. If you are not using Fine Uploader UI or the standalone drag & drop module, you will not be affected by these changes.
Be sure to read about templating in the styling guide.
Templating has been a mess in Fine Uploader UI for quite some time, arguably since day 1. The goal was to clean up this mess in 4.0 so that integrators/designers could more easily customize the look and feel of UI mode without resorting to core mode and developing a custom UI from scratch. There will likely still be some cases where it makes more sense to drop back to Fine Uploader Core and develop a new UI from scratch, but the improvements to templating in UI mode should make that scenario much less likely.
At a high level, the template markup was moved out of the
Uploader in your document. This step made many
text option properties redundant as well, so appropriate
properties were removed. What follows is a more detailed description of these breaking changes, along with instructions
that should make the upgrade process from a 3.x build a bit easier.
templateoption to take an ID (string) or element (pointing to script tag containing template)
template option contained the top-level template markup (sans the file list markup) as a string.
If you wanted to change this, you needed to copy and paste this unwieldy string into your glue code and make appropriate
changes. You also had to be careful about changing any of the CSS classes assigned to these template items. If any
CSS class was removed/renamed, you had to be sure to update the associated
classes option property, since Fine Uploader
UI used the same CSS classes for selection and styling.
In version 4.0, the
template option expects either a string or an
Element as a value (or a
jQuery object if using
the jQuery plug-in wrapper). You may either specify the ID of the container element in your document that contains
the template markup, or you may select the container element yourself. The default value is a string: "qq-template".
The default template HTML file that is bundled with Fine Uploader contains a
<script> with an ID of "qq-template" along
with all supported template items. You can drop this into your document without any changes, and Fine Uploader UI
will work just as it did before. If you want to further customize the template, you can make appropriate changes to
the markup in the
<script> template contents. You can remove almost any item in the template if you don't want it
to be rendered in the DOM. Note that each template item has a CSS class that ends in "-selector" which is used internally
for selecting the item. A second CSS class may be present on the item, used only for styling. You can remove this second
CSS class without fear of breaking the uploader. If you remove the "-selector" CSS class, Fine Uploader will simply
ignore the item, though it will still render in the DOM.
The contents of the old
fileTemplate options have been combined into one template, which must be
included as a
<script> tag with a type of "text/template" in your document (or any hidden container element).
You can use the template contained in the included
default.html file in the
templates directory as-is,
or modify it to match your application.
As mentioned previously, even if you did not make any adjustments to the default
in older versions of Fine Uploader UI, you still must include a template in your document. A default template is
now bundled with Fine Uploader. You can use the bundled HTML file, or copy and paste the template
into your document.
There were a few styling-related changes made to the CSS file that ships with the library.
.qq-hide style, which defaults to
display: none; was also added. You can override this default style
via increased specificity, or you can contribute a new value for this CSS class that Fine Uploader will assign
to any element that it needs to hide. See the
classes option in the styling guide
for more details.
.qq-upload-finished style was removed, as this did not appear to serve a useful purpose anymore.
If you do not want the retry button displayed next to each file automatically when a manual retry is possible, simply omit the retry-related element from your template.
If you do not want to utilize the edit filename feature, either ensure the
autoUpload option is set to true
(this is the default) or remove the edit-filename related elements from your template. Currently, this involves removing
the "qq-edit-filename-icon-selector" and "qq-edit-filename-selector" elements.
classesoption properties, other than the ones listed in styling doc
In most cases, there is no longer any need to define options for each class associated with a UI-mode template item.
Remember, Fine Uploader UI 4.0's default template includes a "-selector" class on each template item specifically for
selecting the item, and another for styling. You can remove or rename the styling class without fear of breaking the
uploader. In fact, omitting most template items is possible as well. The only
classes properties that remain are
ones that are added by Fine Uploader dynamically/on-demand. You can override any of these default values if you'd like
to use one of your own custom CSS classes instead.
Part of the 4.0 template rework included a push to stop assigning/changing style attributes on template items in the
style attribute value to the element, and then change this
display property to a variable appropriate value when
it was time to display the element again. As of 4.0, to hide an element, Fine Uploader adds a
qq-hide CSS class to
the element, which is defined with a default style of
display: none; in the bundled CSS file. When the element must
be visible again, this class is removed. You can override the default CSS class name for hiding elements via
Note that the standalone drag & drop module (which is also used internally by Fine Uploader UI) still sets a
style directly on drop zones when they must be hidden, and changes this to
display: block; to make them visible again.
This was left alone, as we didn't want to break all Fine Uploader Core mode apps that do not include Fine Uploader UI's
default CSS file (since there has never been a dependency on this file when using core mode).
textoption properties, except for
Similar to the changes to the
classes option, there is no longer a need to have options dedicated to text that
appears with template items in most cases. You can easily change the default text in your template. In cases where
Fine Uploader UI dynamically changes text based on conditions,
text options remain for you to adjust if desired.
If you want to disable the default drop zone, simply remove the drop zone related element(s) from your template.
If you want an extra or default drop zone to remain invisible until an item approaches the drop area, simply include
qq-hide-dropzone attribute on the drop zone container. The attribute is present on the drop area in the
default template, but it can be removed, of course.
hideDropZonesBeforeEnteroption in standalone DnD module (replaced w/ qq-hide-dropzone attr)
This is the only breaking change to the standalone drag & drop module. Instead of specifying a value for a
hideDropZonesBeforeEnter option that either hides all drop zones until an item approaches (or not) you can now control
visibility in this respect per-dropzone via a
qq-hide-dropzone attribute on the drop zone container.