Documentation for a historical release of Infusion: 1.3
Please view the Infusion Documentation site for the latest documentation.
If you're looking for Fluid Project coordination, design, communication, etc, try the Fluid Project Wiki.

Uploader Tutorial - v0.4

This documentation refers to the API documents for the v0.4 released version of the Fluid Infusion code. For documentation specific to the trunk version, please see Uploader Tutorial

This page will walk you through an example of adding the Fluid Uploader component to your application.

This tutorial assumes that:

  • you are already familiar with HTML, Javascript and CSS
  • you are familiar with what the Uploader is and does
  • now you just want to know how to add it to your file.

For more general information about the Uploader, see Uploader Design Overview. For technical API documentation, see Uploader API - v0.4.

Important Note

In order to test with the Uploader on a local file system, you will need to make modifications to your Flash settings. Please see Enabling Uploader on Local File Systems for instructions.

Tutorial: How to Use the Uploader

On This Page
Still need help?

Join the fluid-talk mailing list and ask your questions there.

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:
  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.