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.

There are four basic steps to adding the Uploader to your application:

• Step 0: Download and install the Fluid Infusion library
• Step 1: Prepare your markup
• Step 2: Write the script
• Step 3: Add the script to your HTML
• Step 4: Apply styles

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

Step 0: Download and install the Fluid Infusion library

1. Download a copy of the Fluid Infusion component library from:
   • http://fluidproject.org/index.php/downloads
     You only really need the "Minified deployment package," but if you want to actually look at the code, you should download the "Source package."
2. Unpack the zip file you just downloaded, and place the resulting folder somewhere convenient for your development purposes.
   The folder will have the release number in it's name (e.g. fluid-0.4/). The rest of this tutorial will use fluid-0.4 in its examples, but if you downloaded a different version, you'll have to adjust.

Step 1: Prepare your markup

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.

To embed the Uploader into your file, copy and paste the markup below into your file where you want the Uploader to appear:

<div id="single-inline-fluid-uploader" class="fluid-uploader infusion">
  <div class="start">
    <div class="fluid-uploader-queue-wrapper">
      <div class="fluid-scroller-table-head">
        <table cellspacing="0" cellpadding="0">
          <caption>File Queue:</caption>
          <thead>
            <tr>
              <th scope="col" class="fileName">File Name</th>
              <th scope="col" class="fileSize">Size&nbsp;&nbsp;</th>
              <th scope="col" class="fileRemove">&nbsp;</th>
            </tr>
          </thead>
        </table>
      </div>
      <div class="fluid-scroller" tabindex="-1">
        <div class="scroller-inner" tabindex="-1">
          <table cellspacing="0" class="fluid-uploader-queue" tabindex="0">
            <tbody>

            </tbody>
          </table>
          <div class="file-progress"><span class="file-progress-text">76%</span></div>
        </div>
      </div>

      <div class="fluid-uploader-row-placeholder"> click <em>Browse files</em> to add files to the queue </div>

      <div class="fluid-scroller-table-foot">
        <table cellspacing="0" cellpadding="0">
          <tfoot>
            <tr>
              <td class="footer-total">Total:
                 <span class="fluid-uploader-totalFiles">0</span> files
                (<span class="fluid-uploader-totalBytes">0 KB</span>)
              </td>
              <td class="footer-button" align="right" >
                <a href="#" class="fluid-uploader-browse">Browse files</a>
              </td>
            </tr>
          </tfoot>
        </table>
        <div class="total-progress">&nbsp;</div>
      </div>
    </div>
    <div class="fluid-uploader-btns">
      <button type="button" class="fluid-uploader-upload default" >Upload</button>
      <button type="button" class="fluid-uploader-resume default" >Resume</button>
      <button type="button" class="fluid-uploader-pause" >Pause</button>
      <button type="button" class="fluid-uploader-cancel cancel" >Cancel</button>
      <button type="button" class="fluid-uploader-done" >Done</button>
    </div>
  </div>
</div>

<div class="fluid-templates">
  <table id="fluid-uploader">
    <tr id="queue-row-tmplt">
      <td class="fileName" scope="row">File Name Placeholder</td>
      <td class="fileSize">0 KB</td>
      <td class="fileRemove">
        <button type="button" class="removeFile" title="Remove File" tabindex="-1">
          <span class="text-description">Remove file from queue</span>
        </button>
      </td>
    </tr>
    <tr id="queue-error-tmplt" class="queue-error-row"><td colspan="3" class="queue-error"></td></tr>
  </table>
</div>

This template contains all of the elements, IDs and class attributes needed by the Uploader. Combined with the Uploader's style sheets (discussed in Step 3), this markup will display the Uploader dialog in your page.

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.

In this file, write a function that calls the Uploader constructor:

jQuery(document).ready(function () {

  var uploadURL = "";
  var flashURL = "fluid-0.4/fluid-components/swfupload/swfupload_f9.swf";

  myUpload = new fluid.Uploader("single-inline-fluid-uploader", uploadURL, flashURL, settings);

});

This function passes three required parameters to the Uploader constructor:

1. The string ID of the container element ("single-inline-fluid-uploader")
2. The URL of the application that files should be uploaded to (uploadURL)
3. The URL to the Flash object used by the Uploader (flashURL)

Those last two parameters warrant a bit more explanation:

Upload URL

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

For testing purposes (and for the purposes of this tutorial), you probably don't want to be actually uploading files to a server. If this parameter is left blank (i.e. an empty string), then the Uploader will operate in a 'debug' mode, and no files will be transferred anywhere.

Flash URL

The Uploader uses a Flash module called SWFUpload (filename swfUpload_f9.swf) for the actual business of talking to the server. This module is included in the Fluid Infusion package, and will be deployed if you use the war file in the bundle. This URL must reference the location of the .swf file.

For testing purposes (and for the purposes of this tutorial), you likely don't have the files deployed to a server, so this URL must be a relative URL to the current location of the file.

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.

Step 3: Add the script to 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:

<link rel="stylesheet" type="text/css" href="fluid-0.4/fluid-components/css/infusion-theme.css" />
<link rel="stylesheet" type="text/css" href="fluid-0.4/fluid-components/css/Uploader.css" />

<script type="text/javascript" src="fluid-0.4/fluid-components/js/Fluid-all.js"></script>
<script type="text/javascript" src="upload.js"></script>

NOTE that the Fluid-all.js file is minified - all of the whitespace has been removed, so it isn't really human-readable. If you're using the source distribution and you want to be able to debug the code, you'll want to include each of the required files individually. This would look like this:

<link rel="stylesheet" type="text/css" href="fluid-0.4/fluid-components/css/infusion-theme.css" />
<link rel="stylesheet" type="text/css" href="fluid-0.4/fluid-components/css/Uploader.css" />

<script type="text/javascript" src="fluid-0.4/fluid-components/js/jquery/jquery-1.2.6.js"></script>
<script type="text/javascript" src="fluid-0.4/fluid-components/js/jquery/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="fluid-0.4/fluid-components/js/jquery/jARIA.js"></script>
<script type="text/javascript" src="fluid-0.4/fluid-components/js/swfupload/swfupload.js"></script>
<script type="text/javascript" src="fluid-0.4/fluid-components/js/fluid/Fluid.js"></script>
<script type="text/javascript" src="fluid-0.4/fluid-components/js/fluid/Uploader.js"></script>
<script type="text/javascript" src="upload.js"></script>

But all of these individual Javascript files are not necessary to make it work - the Fluid-all.js file has everything you need.

That's it! That's all you need to do to add the Uploader to your document.