Styling

This document applies to Fine Uploader UI mode only, and aims to help you customize the default UI using the built-in templating feature.

Template

A default template, default.html in the templates directory, is bundled with each version. In the future, alternate templates may be included as well. Note that you must include a template in your markup/document when using Fine Uploader UI. Everything should work just fine if you simply use the provided template as is, without changing anything. However, you can certainly customize the default template to match your web application’s look and feel. The rest of this section includes examples of some changes you may want to make to the template.

The templates are, by default, included in a <script> tag with the type attribute set to “text/template”. The template does not have to be included in a <script> tag. For example, you may instead include the template in a hidden <div>. Fine Uploader simple needs to be able to locate the template element container in the document.

Re-style the progress bar

Don’t like the default progress bar included with Fine Uploader’s CSS file? No problem! You can easily use, for example, a Bootstrap-styled progress bar. Just include Bootstrap in your project and change this:

<div class="qq-progress-bar-container-selector">
    <div class="qq-progress-bar-selector qq-progress-bar"></div>
</div>

To this:

<div class="qq-progress-bar-container-selector progress">
    <div class="qq-progress-bar-selector bar"></div>
</div>

You can do the same for the total progress bar (qq-total-progress-bar-container).

Omit a portion of the template that does not apply to your app

You can omit any element of the template that does not apply to your uploader except for:

• The parent div that contains the contents of the template (qq-uploader-selector element)
• The file list container element (qq-upload-list-selector element)
• The immediate child container of the file list container element. You can certainly change the type of tag here though.

Otherwise, any portion of the template can simply be omitted. For example, if you don’t want to utilize the edit filename feature, simply omit any elements with class names that start with qq-edit-filename. If you don’t want to have the delete button appear after a successful upload, omit the qq-upload-delete-selector element. If you don’t want the progress bar at all, omit the qq-progress-bar elements, etc, etc.

Change default text

Any of the text nodes in the template can be changed to match your language or preferences. In some cases, Fine Uploader UI dynamically sets text, such as with the qq-upload-status-text-selector and qq-upload-size-selector elements. See the text option for adjusting these types of strings.

Re-arrange the order of the template elements

You may also change the order of the elements in the template. Note that you should not move file-related elements out of the qq-upload-list-selector container or it’s immediate child container though.

Move the file list to an alternate location in the DOM

If you would like to locate the file list (contents of the qq-upload-list-selector element) elsewhere in your document, you may do so via the listElement option which allows you to specify an existing container element where Fine Uploader UI will render the file list item elements.

Move the default drop zone into the file list

Suppose you want to combine the file list (qq-upload-list-selector element) and the drop zone (qq-upload-drop-area-selector element). You can accomplish this simply by following these steps:

First, make the file list a child of the drop zone:

<div class="qq-upload-drop-area-selector">
    <ul class="qq-upload-list-selector qq-upload-list">
        <li>
            ....
        </li>
    </ul>
</div>

Notice that the default styling class for the drop area has been removed, you may want to contribute your own CSS class to match your web application’s style. Also notice that the qq-hide-dropzone attribute has been omitted from the drop area container. By removing this (or setting its value to “false”, we are telling Fine Uploader UI to keep the contents of this drop zone visible at all times. When this attribute is present, the contents are only visible when an item enters the drop zone.

Then, you may want to specify some custom styles for the drop zone. Perhaps a min-height is important to ensure that the drop zone is not 0-sized when the uploader first loads (before any files have been submitted). You may also want to consider setting a background image, adjusting the opacity (so the default background color that Fine Uploader UI adds when you enter the drop zone is visible), or something else. You can contribute these styles directly to the qq-drop-area-selector element in the template via a style attribute, or define a CSS class elsewhere in the document with these styles and simply append this custom class to the drop-area element signature.

Customize the buttons/links

It is trivial to re-style the delete, cancel, retry, and upload buttons. For example, you can utilize Bootstrap’s button styling to re-skin the upload button by changing this:

<div class="qq-upload-button-selector qq-upload-button">
    <div>Upload a file</div>
</div>

to this:

<div class="qq-upload-button-selector btn">
    <div>Upload a file</div>
</div>

Include other custom elements in your template

Suppose you want to include a link to the uploaded file next to each file item element. You can modify the template to include a styled anchor link, hidden initially, and then show the anchor and set its href attribute in your complete event handler, once you know the path of the file on your server.

To do this, the file list portion of the template can be modified to include this link as the last child:

<ul class="qq-upload-list-selector qq-upload-list">
    <li>
        ...
        <a class="view-btn hide btn">View</a>
    </li>
</ul>

Your complete event handler would look something like this:

$("#myUploader").on("complete", function(event, id, name, response) {
    var serverPathToFile = response.filePath,
        $fileItem = $(this).fineUploader("getItemByFileId", id);

    if (response.success) {
        $fileItem.find(".view-btn")
            .attr("href", serverPathToFile)
            .removeClass("hide");
    }
});

classes option

A classes option allows you to change some default class names that Fine Uploader may add to template elements dynamically/on-demand. The following classes option properties exist in Fine Uploader UI mode:

Dialogs

Fine Uploader UI mode — by default — uses the native browser implementations of alerts, confirms, and messages to show user notifications when necessary. More than likely, you are going to want to override these. To provide your own dialogs just provide your own functions for the showMessage, showConfirm, and/or showPrompt options.

• showMessage: function(message) {...} - You may want to change the default alert dialog implementation and messages as you see fit. This is possible by overriding the showMessage function option. The default showMessage function simply invokes alert with the message text. One instance in which this is used is when the user attempts to select an invalid file for upload. There are general message types with default text that can be overriden as well.
• showConfirm: function(message, okCallback, cancelCallback) {...} - This function is used to display a confirm dialog. One such feature that optionally uses this is the deleteFile feature. Note that this is a promissory callback, meaning it requires a qq.Promise to be returned.The default implementation uses window.confirm, but you may override this with something a bit nicer, if you choose. The okCallback will be executed if the user clicks “ok” and the cancelCallback if the user clicks “cancel”. The cancelCallback is optional, but the okCallback is required.
• showPrompt: function(message, defaultValue) {...} - This function is used to prompt the user for a value. Note that this is a promissory callback, meaning it requires a qq.Promise to be returned. The qq.Promise documentation includes a simple example that overrides this default implementation using bootbox. The default implementation here simply uses window.prompt.