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.
Important Note about using the Uploader on a local file system
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
This component is in Preview status
Join the infusion-users 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:
- Setup: Download and install the Fluid Infusion library
- Step 1: Prepare your markup
- Step 2: Write the script
- Step 3: Add the script and styles to your HTML
The rest of this tutorial will explain each of these steps in detail.
Setup: Download and install the Fluid Infusion library
- Download a copy of the Fluid Infusion component library from:
- http://fluidproject.org/products/fluid-infusion/download-infusion/
You only really need the "Minified deployment package," but if you want to actually look at the code, you should download the "Source package."
- http://fluidproject.org/products/fluid-infusion/download-infusion/
- 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 its name (e.g. infusion-1.4/). The rest of this tutorial will use infusion-1.4 in its examples, but if you downloaded a different version, you'll have to adjust.
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.
This template contains all of the elements and class attributes needed by the Uploader. Combined with the Uploader's style sheets, this markup will display the Uploader on your page.
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.
In this file, write a function that calls the Uploader constructor:
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"
}
});
});
});
This function passes two required parameters to the Uploader constructor:
- A selector that specifies the container for the Uploader's markup. Using this default markup, this will be
".flc-uploader". - 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):
onFileSuccess: function (file, responseText, xhr){
// example assumes that the server code passes the new image URL in the responseText
jQuery('#image-space').append('<img src="' + responseText + '" alt="' + file.name +'" />');
}
Example 2: A listener on onFileError to display the error returned from the server if the image is failed at being uploaded (The fourth parameter "xhr" is new in 1.4):
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);
}
Example 3: A listener on afterUploadComplete to load the next page in a multi-step process:
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;
}
}
Example 4: The previous three examples added to the above constructor:
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:
var templateURLSelector = "infusion/src/webapp/components/uploader/html/Uploader.html .fl-uploader";
$("#uploader-contents").load(templateURLSelector, null, function () {
// Initialize the Uploader
fluid.uploader(".flc-uploader", {
demo: true
// Other options go here.
});
});
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:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Uploader</title>
<link rel="stylesheet" type="text/css" href="infusion/src/webapp/framework/fss/css/fss-reset.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/webapp/framework/fss/css/fss-layout.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/webapp/components/uploader/css/Uploader.css" />
<script type="text/javascript" src="infusion/InfusionAll.js"></script>
<!-- Your script for initializing the Uploader -->
<script type="text/javascript" src="uploader.js"></script>
</head>
<body>
<!-- Basic upload controls, used when flash is not installed (IE) or JavaScript is unavailable -->
<form action="uploadFiles" method="post" enctype="multipart/form-data" class="fl-progEnhance-basic" id="single-file-uploader">
<p>Use the Browse button to add a file, and the Save button to upload it.</p>
<input name="fileData" type="file" />
<input class="fl-uploader-basic-save" type="submit" value="Save"/>
</form>
<div id="uploader-contents">
<!-- The Uploader's template will be injected via AJAX into this container. -->
</div>
<div id="image-space">
<!-- The container to display all the uploaded images. -->
</div>
<div id="server-error">
<!-- The container to display the server returned error. -->
</div>
</body>
</html>
If your site is using the Fluid Skinning System (FSS), you may also want to link to the fluid.reset.css style sheet for more consistency in styling across all browsers.
NOTE that the InfusionAll.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="infusion/src/webapp/framework/fss/css/fss-reset.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/webapp/framework/fss/css/fss-layout.css" />
<link rel="stylesheet" type="text/css" href="infusion/src/webapp/components/uploader/css/Uploader.css" />
<!-- Fluid and jQuery Dependencies -->
<script type="text/javascript" src="infusion/src/webapp/lib/jquery/core/js/jquery.js"></script>
<script type="text/javascript" src="infusion/src/webapp/lib/jquery/ui/js/jquery.ui.core.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/core/js/jquery.keyboard-a11y.js"></script>
<script type="text/javascript" src="infusion/src/webapp/lib/jquery/plugins/scrollTo/js/jquery.scrollTo.js"></script>
<script type="text/javascript" src="infusion/src/webapp/lib/swfobject/js/swfobject.js"></script>
<script type="text/javascript" src="infusion/src/webapp/lib/swfupload/js/swfupload.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/core/js/Fluid.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/core/js/DataBinding.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/core/js/FluidIoC.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/core/js/FluidDocument.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/core/js/FluidView.js"></script>
<script type="text/javascript" src="infusion/src/webapp/framework/enhancement/js/ProgressiveEnhancement.js"></script>
<!-- Uploader dependencies -->
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/Uploader.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/FileQueue.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/progress/js/Progress.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/FileQueueView.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/FlashUploaderSupport.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/Flash9UploaderSupport.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/HTML5UploaderSupport.js"></script>
<script type="text/javascript" src="infusion/src/webapp/components/uploader/js/DemoUploadManager.js"></script>
<!-- Your script for initializing the Uploader -->
<script type="text/javascript" src="upload.js"></script>
But all of these individual Javascript files are not necessary to make it work - the InfusionAll.js file has everything you need.
That's it! That's all you need to do to add the Uploader to your site.