Scenario

Suppose you are developing a content management system that will allow users to upload various types of files. This tutorial will show you how to use the Fluid Uploader to provide your users with easy-to-use multiple file upload capability.

...

The rest of this tutorial will explain each of these steps in detail.

...

...

Step 1: Prepare your markup

There is an HTML template for the Uploader located in your Infusion download bundle at components/uploader/html/Uploader.html. This file contains all the markup you'll need to use the Uploader. Use this template as a starting point for your own page, or copy/paste the markup within the div id="uploader-contents" into your site as desired.

...

Let's assume that you're starting with an HTML file, say myapp.html, that will present the user with a user interface for uploading files. This file will have to include the necessary markup for the Uploader interface, so copy/paste the <div id="uploader-contents"> element and everything inside it into the body of your myapp.html file.

...

Step 2: Write the script

You'll need to create a file, say upload.js, to contain your initialization script - the script you write to apply the Uploader to your markup.

...

1. A selector that specifies the container for the Uploader's markup. Using this default markup, this will be ".flc-uploader".
2. A selector that specifies the container to show if the user's system doesn't meet the requirements for using Uploader. Using this default markup, this will be ".fl-progEnhance-basic

Integrate with your application by adding listeners to respond to Uploader events.

Example 1: A listener on onFileSuccess to display a newly uploaded image on the page (The third parameter "xhr" is new in 1.4):

...

jQuery(document).ready(function () {
    // Load the Uploader's template via AJAX and inject it into this page.
    var templateURLSelector = "infusion/src/webapp/components/uploader/html/Uploader.html .fl-uploader";
    $("#uploader-contents").load(templateURLSelector, null, function () {
        
        // Initialize the Uploader
        var myUpload = fluid.uploader(".flc-uploader", {
            components: {
                strategy: {
                    options: {
                        flashMovieSettings: {
                            flashURL: "infusion/src/webapp/lib/swfupload/flash/swfupload.swf",
                            flashButtonImageURL: "infusion/src/webapp/components/uploader/images/browse.png"
                        }
                    }
                }
            },
            queueSettings: {
                // Set the uploadURL to the URL for posting files to your server.
                uploadURL: "http://myserver.com/uploadFiles"
            },
            listeners: {
                onFileSuccess: function (file, responseText, xhr) {
                    // the server code passes the new image URL in the responseText
                    $('#image-space').append('<img src="' + responseText + '" alt="' + file.name + '" class="image-frame" />');
                },
                onFileError: function (file, error, status, xhr) {
                	  // example assumes that the server code passes the reason of the failure in the xhr
                    $('#server-error').append(file.name + " - " + xhr.responseText + "<br />");
                },
                afterUploadComplete: function () {
                    var myNextStepURI = "../BrowseImages/";

                    // first check to see if the file queue is empty and there haven't been any errors
                    if (myUpload.queue.getReadyFiles().length === 0 && myUpload.queue.getErroredFiles().length === 0) {
                        // then go somewhere else
                        window.location.href = myNextStepURI;
                    }
                }
            }
        });
    });
});

Uploader Options

There are a couple of key Uploader options you'll need to customize for your application. For information about other options supported by the Uploader, take a look at the Uploader API documentation.

Upload URL

When your application is live, the Uploader will need to know where on your server to upload the files to. This parameter (uploadURL) should reference the server-side action that can accept the uploaded files and process them accordingly.

Flash URL

The Flash version of the Uploader is used and only used by IE. It uses a third-party library called SWFUpload for the actual business of talking to the server. This module is included in the Fluid Infusion package. The flashURL option must reference the location of the swfupload.swf file. The default setting works with the directory structure for Uploader.html. If your paths are different, you'll need to override this option with a URL that is correct for your server.

NOTE: If the .swf file is on your local file system, you will need to make modifications to your Flash plugin's security settings. See Enabling Uploader on Local File Systems for instructions.

demo

For testing purposes (and for the purposes of this tutorial), you probably don't want to be actually uploading files to a server.
In that case, set the Uploader's demo option to true, like this:

...

In demo mode, the Uploader behaves as if it is sending files to the server and receiving responses from the server, but there is not actual file transfer.

...

Step 3: Write your HTML

You'll need to add your initialization script, along with the Fluid library and Uploader style sheets, to you HTML file, as shown below:

...