jQuery Ajax uploader plugin (with progress bar!)
Do your web applications ever involve letting the user upload a file? If so, how’s the end-user experience: do you show a nice progress bar during the upload, or do you just leave the user waiting for minutes, with no clue when (if ever) the upload will complete?
Please show a progress bar, otherwise users will be justified in hating you. Check out this video to see one way it can work:
If you’re not seeing a video here, your feed reader is hiding it. View this post in a browser to see the video.
Those of you who attended my ASP.NET MVC talk at DDD7 last weekend might recognise this 
To create this behaviour, I implemented a simple jQuery plugin that replaces normal <input type=”file”/> elements with funky Ajaxy asynchronous uploader widgets. Behind the scenes, it uses the excellent SWFUpload library. All the clever stuff is in SWFUpload; all I did is set up the progress bar / cancellation behaviours, and make it easier to use if you’re already using jQuery.
Notice that it still works if the user doesn’t have JavaScript running in their browser. It gracefully degrades to “traditional” <input type=”file”/> behaviour. This is known as progressive enhancement *or *unobtrusive JavaScript.
Download
Here are all the files you need to accomplish this: Download jQuery-asyncUpload-0.1.js**. **
Setup instructions
Uploading files via Ajax, by nature, involves setting things up both on the server and on the client. The most reliable way to get this working successfully in your own app is to download the demo ASP.NET MVC project (see the end of this post) and copy the relevant aspects of its workings into your own app.
Nonetheless, here is an outline of the steps needed to get jQuery-asyncUpload-0.1.js working in your app, assuming you’ve already got jQuery in there:
1. Add jQuery-asyncUpload-0.1.js, swfupload.js, and swfupload.swf to your project. In an ASP.NET MVC app, you might like to put these in /Scripts.
2. Add script tags to reference the JavaScript files.
<head> <!-- Adjust the file paths as needed for your project --> <script src="/Scripts/jquery-1.2.6.min.js"></script> <script src="/Scripts/swfupload.js"></script> <script src="/Scripts/jquery-asyncUpload-0.1.js"></script> </head>
3. Add an old-style HTML file upload control to one of your pages:
<input type="file" id="yourID" name="yourID" />
- Add a jQuery statement that replaces this file upload control with an asynchronous uploader when JavaScript is available:
<script> $(function() { $("#yourID").makeAsyncUploader({ upload_url: "/Home/AsyncUpload", // Important! This isn't a directory, it's a HANDLER such as an ASP.NET MVC action method, or a PHP file, or a Classic ASP file, or an ASP.NET .ASHX handler. The handler should save the file to disk (or database). flash_url: '/Scripts/swfupload.swf', button_image_url: '/Scripts/blankButton.png' }); }); </script>
These options are explained later in this blog post. You must make sure to correctly reference the location of swfupload.swf, and put a button image wherever button_image_url specifies.
- Add some CSS rules to style the progress bar. I’m using the following, though bear in mind it has some nasty hacks to make IE do an inline float properly. CSS gurus might structure this more cleanly.
DIV.ProgressBar { width: 100px; padding: ; border: 1px solid black; margin-right: 1em; height:.75em; margin-left:1em; display:-moz-inline-stack; display:inline-block; zoom:1; *display:inline; } DIV.ProgressBar DIV { background-color: Green; font-size: 1pt; height:100%; float:left; } SPAN.asyncUploader OBJECT { position: relative; top: 5px; left: 10px; }
- At this point, check you have something working. The visitor should now be able to select a file to upload, and should immediately get an alert box saying “Error 404” – that’s because you’ve configured the control to do an asynchronous upload to /Home/AsyncUpload, but your web app probably doesn’t have anything at that URL.
Also, if you use FireBug to inspect the DOM, you’ll see that your <input type=”file” /> has been dynamically replaced with the following:
<span class="asyncUploader"> <div class="ProgressBar" style="display: none;"> <!-- This is the progress bar itself - you can style it with CSS --> </div> <object type="application/x-shockwave-flash" ... > ... SWF config here ... </object> <input type="hidden" name="yourID_filename"/> <input type="hidden" name="yourID_guid"/> </span>
Those two hidden inputs let you keep track of any file that was asynchronously uploaded.
-
Work on your web app so that it *does* handle file uploads to /Home/AsyncUpload (or whatever URL you’ve configured in step 4). The handler should save the uploaded file to disk, then return a unique token, such as a GUID or filename, to will identify the file you just uploaded. See the demo project for a simple way to do this using ASP.NET MVC.
-
When the containing form is finally submitted, check whether a file was sent with the request. This will happen if the user doesn’t have JavaScript enabled, as they’ll revert to traditional uploading behaviour. Also check for the hidden inputs called yourID_guid and yourID_filename – these will be populated if the visitor *does* have JavaScript enabled, and reflect any file that was uploaded asynchronously.
Further configuration
The asynchronous uploader plugin has plenty of properties you can configure in step 4 above:
| Property | Meaning | Example |
| flash_url | Location of swfupload.swf | “/Scripts/swfupload.swf” |
| upload_url |
URL of the handler to which files will be asynchronously sent</p>
Important: This is not the name of a directory or file on your server’s hard disk. It is the URL of a handler, such as an ASP.NET MVC action method, or a PHP page, or a classic ASP page, or an ASP.NET WebForms .ASHX handler, which will receive the file. It remains your job to implement such a handler and then save the incoming file to disk or database. For an example, see the ASP.NET MVC demo project at the end of this blog post.
|
“/Home/AsyncUpload” |
| file_size_limit | Files above this size will be rejected before uploading even begins | “3 MB” |
| file_types | “Select files” popup will only show files of this type | “*.jpg; *.gif” |
| file_types_description | “Select files” popup will use this caption to describe the selectable file types | “All images” |
| button_image_url | Location of an image to be used for the “Choose file” button | “blankButton.png” |
| button_image_width, button_image_height | Dimensions of “Choose file” button | 109 |
| button_text | Text that appears on the “Choose file” button | "<font face=’Arial’ size=’13pt’>Choose file</font>" |
| disableDuringUpload | Elements matching this jQuery selector will be disabled while an upload is in progress (useful to prevent form submission during async upload). | “INPUT[type=’submit’]” |
| existingFilename | Prepopulates the control with the name of a file already uploaded (useful when retaining state across multiple posts) | “somefile.zip” |
| existingGuid | Prepopulates the control with the arbitrary unique token you’ve given to a file already uploaded (useful when retaining state across multiple posts) | “ec42555e-bfe7-45b0-87bf-36b1299f0398” |
| existingFileSize | Prepopulates the control with the size, in bytes, of a file already uploaded (useful when retaining state across multiple posts) | 548293 |
| debug | Turns on SWFUpload’s debugging console | true |
Demo project
The easiest way to understand all this is to check out a completed implementation. Here’s one written for ASP.NET MVC.
To compile and run this, you’ll need Visual Studio 2008 and ASP.NET MVC Beta. It saves asynchronously-uploaded files to the folder ~/App_Data/Files, giving each one a GUID as a filename. When you finally submit the form, it simply displays the filename and GUID of whatever file you uploaded. In a real app, you wouldn’t display the GUID to the end user, but would instead just use it to locate their file later.
