Uploading files using Html5

The XMLHttpRequest object has gotten a facelift in the Html5 specifications. Specifically the XMLHttpRequest Level 2 specification (currently the latest version) that has included the following new features: 

1. Handling of byte streams such as File, Blob and FormData objects for uploading and downloading
2. Progress events during uploading and downloading
3. Cross-origin requests
4. Allow making anonymous request - that is not send HTTP Referer
5. The ability to set a Timeout for the Request

In this post we’ll look more closely at #1 and #2. In particular, uploading of files using XMLHttpRequest and providing upload progress information to the end-user. Note that this solution does not require any change to the server side, at least insofar as handling the multipart/form-data protocol. So existing server side logic should remain unchanged, which makes adapting this technology that much easier.

Figure 1: Showing the File Upload screen -Upload just started

Figure 2: Showing the File Upload screen with upload completed.

Notice in the images above the following pieces of information made available to the user: 

1. Information on the file that has been selected such as
   • File Name
   • File Size
   • Mime Type
2. A Progress bar with percent complete
3. The upload speed or upload bandwidth
4. The approximate time remaining
5. The bytes uploaded thus far
6. A response from the server side (the organge box)

Item #6 above may not sound important, but in fact is quite important in this context because, remember that the user is not navigating away from this page as she normally would after submitting an html form. Because we're using XMLHttpRequest, the uploading is happening in the background. The page the user is on remains intact. Which is a nice feature to have if your business process can work with it.

Html5 Progress Event

As per the Html5 Progress Events spec, the Html5 progress event provides the following information relevant to this conversation 

1. total - Total bytes being transferred
2. loaded - Bytes uploaded thus far
3. lengthComputable - Specifies if the total size of the data/file being uploaded is known

You should notice that we need to use these two pieces of information to calculate (figure out) all of the other information we're displaying to the user. It is fairly simple to figure out all of the other information given the above two pieces of information but it does involve quite a bit of extra coding and setting up a timer.

Html5 Progress Event - What it should have been

Considering that those who go down the route of providing upload progress information to the end user will require to show all of the other information to the end user as well, the Html5 Progress Event specifications should have accounted for this need as well, as it would be fairly simple for browser vendors to provide these additional pieces of information each time the progress event is raised. So I propose that the progress event should be modified to the following: 

1. total - Total bytes being transferred
2. loaded - Bytes uploaded thus far
3. lengthComputable - Specifies if the total size of the data/file being uploaded is known
4. transferSpeed as a long
5. timeRemaining as a JavaScript Date object

Html5 Upload using XMLHttpRequest

I've provided a Uploading files using Html5 with Progress indication demo for those who want to jump right to it. All of the JavaScript code required is in the page. However, because the demo is a real world demo there are a number of CSS styles in use, and the layout of the page (the Html) is fairly complex. In this article we work with a minimalistic version of the Html and JavaScript so as to keep things simple and understandable.

Let's get started

The entire code listing for the minimalistic but functional implementation can be found in Code Listing 6. Each aspect of the minimalistic Html/JavaScript is explained in detail in the rest of this article. Below, is a very simple Html form. This Html is no different then the Html you'd use to do a regular Html/HTTP file upload you'd use today (Html4 and pretty much any previous version of Html).

<!DOCTYPE html>

<html>

<head>

    <title>Upload Files using XMLHttpRequest - Minimal</title>

</head>

<body>

  <form id="form1" enctype="multipart/form-data" method="post" action="Upload.aspx">

    <div class="row">

      <label for="fileToUpload">Select a File to Upload</label><br />

      <input type="file" name="fileToUpload" id="fileToUpload" onchange="fileSelected();"/>

    </div>

    <div id="fileName"></div>

    <div id="fileSize"></div>

    <div id="fileType"></div>

    <div class="row">

      <input type="button" onclick="uploadFile()" value="Upload" />

    </div>

    <div id="progressNumber"></div>

  </form>

</body>

</html>

Code Listing 1: The bare minimum Html Page

Notice that the <input type="file"/> element has the onchange event assigned to a JavaScript method called fileSelected(). So essentially, each time someone selects a file by browsing to a file on their local system, this event is raised. The fileSelected() JavaScript method looks like the following.

function fileSelected() {

  var file = document.getElementById('fileToUpload').files[0];

  if (file) {

    var fileSize = 0;

    if (file.size > 1024 * 1024)

      fileSize = (Math.round(file.size * 100 / (1024 * 1024)) / 100).toString() + 'MB';

    else

      fileSize = (Math.round(file.size * 100 / 1024) / 100).toString() + 'KB';

    document.getElementById('fileName').innerHTML = 'Name: ' + file.name;

    document.getElementById('fileSize').innerHTML = 'Size: ' + fileSize;

    document.getElementById('fileType').innerHTML = 'Type: ' + file.type;

  }

}

Code Listing 2: The fileSelected() JavaScript method

The first line of code in the method is doing something you've not seen or done before. Essentially, once you have a reference to the <input type="file"/> element, you have access to what is called a FileList object which is new in Html5 and is part of the File API specifications of Html 5. A FileList object is a collection of files. More specifically, it is a collection of File objects. A File object has the following properties.

1. name - The name of the file (excluding any path)
2. type - The MIME type of the file (in lower case)
3. size - The size of the file in bytes

This is already getting interesting isn't it? We have access to this information on the client side! In fact the File API gives us access to the contents of the file (the file stream or bytes) on the client side too, using the FileReader object. We won't be dealing with the FileReader in this example, so I'm not going to overwhelm you with yet another new object. We have a couple of new objects to discuss yet. You could use the information the File object provides you to say, prevent users from uploading files larger than the certain size. Or you could use the type property (MIME type) to figure out the type of file the user is attempting to upload and change the behavior of your form (on the client side of course). The above JavaScript method populates the grey box with grey text (in Figures 1 & 2 above) with the information the File object provides us about the selected file. The file size is in bytes, so there is logic in the method to convert the size into a human readable form, such as 15.65MB instead of 15795748864 bytes. After the user has selected a file she'll want to upload the file and so she's going to click on the Upload button. Notice in the code listing for the Html form (Code Listing 1) that the Upload button has its onclick event assigned to the uploadFile() JavaScript method.

function uploadFile() {

  var xhr = new XMLHttpRequest();

  var fd = document.getElementById('form1').getFormData();

  /* event listners */

  xhr.upload.addEventListener("progress", uploadProgress, false);

  xhr.addEventListener("load", uploadComplete, false);

  xhr.addEventListener("error", uploadFailed, false);

  xhr.addEventListener("abort", uploadCanceled, false);

  /* Be sure to change the url below to the url of your upload server side script */

  xhr.open("POST", "UploadMinimal.aspx");

  xhr.send(fd);

}

Code Listing 3: The uploadFile() JavaScript method

In the second line of this method you'll see another object (FormData) that we've never seen nor used before. You're not really seeing it, but we do get a reference to it using the getFormData() method of the <form> element. A FormData object is similar to a dictionary, a collection of name/value pairs. Where the name part is the name of a form field (as defined in the Html page) and the value is the value of this field. The value part can be a string, number or even a File object, as you can see in Code listing 4. So when you call the getFormData() method on the form you get a reference to a FormData object that holds a collection of name/value pairs of that form. You can use this reference as the information you want to send to the server side script. This makes it really simple to submit the entire form. Now you could create an instance of a FormData object manually and send that to the server or you could add additional information to the FormData before sending it to the server side script.

Code listing 4, below shows you an example of how you would create an instance of a FormData object, assign some arbitrary fields and their values, including a reference to a File object (the file selected by the user using the <&tl;file type="file"> element.

var fd = new FormData();

fd.append("author", "Shiv Kumar");

fd.append("name", "Html 5 File API/FormData");

fd.append("fileToUpload", document.getElementById('fileToUpload').files[0]);

Code Listing 4: Manually creating a FormData instance

Going back to Code Listing 3, you'll notice we've subscribed to a few events of the XMLHttpRequest object. In particular, pay attention to the first line after the event listners comment in the code. xhr.upload.addEventListener("progress", uploadProgress, false); The progress event we subscribe to is not that of the XMLHttpRequest instance, but rather the upload property of the XMLHttpRequest instance, which is an XMLHttpRequestUpload type that is really an event target that has a progress event we can subscribe to in order to get progress information on the upload that is taking place. We don't have to worry about this object. Just remember, when using XMLHttpRequest for uploading data to the server, you must subscribe to its upload property's progress event.

function uploadProgress(evt) {

  if (evt.lengthComputable) {

    var percentComplete = Math.round(evt.loaded * 100 / evt.total);

    document.getElementById('progressNumber').innerHTML = percentComplete.toString() + '%';

  }

  else {

    document.getElementById('progressNumber').innerHTML = 'unable to compute';

  }

}

function uploadComplete(evt) {

  /* This event is raised when the server send back a response */

  alert(evt.target.responseText);

}

function uploadFailed(evt) {

  alert("There was an error attempting to upload the file.");

}

function uploadCanceled(evt) {

  alert("The upload has been canceled by the user or the browser dropped the connection.");

}

Code Listing 5: The implementation of the various event handlers

The code listing above is pretty self explanatory so there is nothing much to say here.

The Minimalistic Solution

The Code listing below is the entire Html page including the JavaScript and Html required to get a bear minimum File upload with progress indicator working. I've intentionally kept it simple so if you want to do your own layout and information display you can start with this and expand it. Html5 also introduces a progress element that can be used to show progress. The progress element has max and value and so it makes it really simple to show progress. However, at the time of this writing, only Chrome 6 supports this element so I've not used it in the minimalistic solution.

<!DOCTYPE html>

<html>

<head>

    <title>Upload Files using XMLHttpRequest - Minimal</title>

    <script type="text/javascript">

      function fileSelected() {

        var file = document.getElementById('fileToUpload').files[0];

        if (file) {

          var fileSize = 0;

          if (file.size > 1024 * 1024)

            fileSize = (Math.round(file.size * 100 / (1024 * 1024)) / 100).toString() + 'MB';

          else

            fileSize = (Math.round(file.size * 100 / 1024) / 100).toString() + 'KB';

          document.getElementById('fileName').innerHTML = 'Name: ' + file.name;

          document.getElementById('fileSize').innerHTML = 'Size: ' + fileSize;

          document.getElementById('fileType').innerHTML = 'Type: ' + file.type;

        }

      }

      function uploadFile() {

        var fd = new FormData();

        fd.append("fileToUpload", document.getElementById('fileToUpload').files[0]);

        var xhr = new XMLHttpRequest();

        xhr.upload.addEventListener("progress", uploadProgress, false);

        xhr.addEventListener("load", uploadComplete, false);

        xhr.addEventListener("error", uploadFailed, false);

        xhr.addEventListener("abort", uploadCanceled, false);

        xhr.open("POST", "UploadMinimal.aspx");

        xhr.send(fd);

      }

      function uploadProgress(evt) {

        if (evt.lengthComputable) {

          var percentComplete = Math.round(evt.loaded * 100 / evt.total);

          document.getElementById('progressNumber').innerHTML = percentComplete.toString() + '%';

        }

        else {

          document.getElementById('progressNumber').innerHTML = 'unable to compute';

        }

      }

      function uploadComplete(evt) {

        /* This event is raised when the server send back a response */

        alert(evt.target.responseText);

      }

      function uploadFailed(evt) {

        alert("There was an error attempting to upload the file.");

      }

      function uploadCanceled(evt) {

        alert("The upload has been canceled by the user or the browser dropped the connection.");

      }

    </script>

</head>

<body>

  <form id="form1" enctype="multipart/form-data" method="post" action="Upload.aspx">

    <div class="row">

      <label for="fileToUpload">Select a File to Upload</label><br />

      <input type="file" name="fileToUpload" id="fileToUpload" onchange="fileSelected();"/>

    </div>

    <div id="fileName"></div>

    <div id="fileSize"></div>

    <div id="fileType"></div>

    <div class="row">

      <input type="button" onclick="uploadFile()" value="Upload" />

    </div>

    <div id="progressNumber"></div>

  </form>

</body>

</html>

Code Listing 6: The Complete but minimalistic code listing

Well, that pretty much covers the minimalistic version of the new Html5 feature. Getting at the other information that you see in Figure2 is mathematical really. It is quite a bit of extra work to not only get at the information, but to display and animate etc. For instance to get the rate of upload (the upload speed). We do the following: 1. in the uploadProgress(evt) event, should store the evt.loaded and evt.total in global variables. 2. We set up a timer event to fire every second. 3. In the timer callback we get the difference of the number of bytes transfered between now and the last time the callback was called (so 1 second ago). 4. That gives us the number of bytes per second. Which is the upload speed. Note that in the demo I set up the timer to fire every 500 milliseconds to get more granularity. As a result the difference between the number of bytes is doubled since the number of bytes is really the number of bytes transferred in half a second. I won't go into how to find the time remaining, but it's all there in the demo. Do a "view source" to see the code in the demo's html page. I hope you found this article helpful.