Table of Contents for

JavaScript Web Applications

Dragging is fairly straightforward. To make an element draggable, set its draggable attribute to true.

<div id="dragme" draggable="true">Drag me!</div>

Now we have to associate that draggable element with some data. We can do this by listening to the dragstart event and calling the event’s setData() function:

var element = $("#dragme");

element.bind("dragstart", function(event){
  // We don't want to use jQuery's abstraction
  event = event.originalEvent;

  event.dataTransfer.effectAllowed = "move";
  event.dataTransfer.setData("text/plain", $(this).text());
  event.dataTransfer.setData("text/html", $(this).html());
  event.dataTransfer.setDragImage("/images/drag.png", -10, -10);
});

jQuery provides an abstraction of the event, which doesn’t contain the dataTransfer object we need. Conveniently, the abstracted event has an originalEvent attribute, which we can use to access the drag/drop APIs.

As demonstrated above, the event has a dataTransfer object, which has the various drag and drop functions we need. The setData() function takes a mimetype and string data. In this case, we’re setting some text and text/html data on the drag event. When the element is dropped, and a drop event is triggered, we can read this data. Likewise, if the element is dragged outside the browser, other applications can handle the dropped data according to which file types they support.

When dragging text, use the text/plain type. It’s recommended to always set this as a fallback for applications or drop targets that don’t support any of the other formats. Dragged links should have two formats: text/plain and text/uri-list. To drag multiple links, join each link with a new line:

// Dragging links
event.dataTransfer.setData("text/uri-list", "http://example.com");
event.dataTransfer.setData("text/plain", "http://example.com");

// Multiple links are separated by a new line
event.dataTransfer.setData("text/uri-list", "http://example.com\nhttp://google.com");
event.dataTransfer.setData("text/plain", "http://example.com\nhttp://google.com");

The optional setDragImage() function controls what is displayed under the cursor during drag operations. It takes an image source and x/y coordinates, the position of the image relative to the cursor. If it’s not supplied, you just get a ghostly clone of the dragged element. An alternative to setDragImage() is addElement(element, x, y), which uses the given element to update the drag feedback. In other words, you can provide a custom element to be displayed during drag operations.

You can also allow users to drag files out of the browser by setting the DownloadURL type. You can specify a URL to the file’s location, which the browser will subsequently download. Gmail uses this to great effect by allowing users to drag and drop email attachments straight out of the browser onto the desktop.

The bad news is that this is currently only supported by Chrome, and it is rather undocumented. It can’t hurt to use it, though, and hopefully other browsers will add support in the future. The DownloadURL format’s value is a colon (:)-separated list of file information: the mime, name, and location.

$("#preview").bind("dragstart", function(e){
  e.originalEvent.dataTransfer.setData("DownloadURL", [
    "application/octet-stream",    // MIME type 
    "File.exe",                    // File name
    "http://example.com/file.png"  // File location
  ].join(":"));
});

You can see the full example of HTML5’s drag/drop API in this book’s accompanying assets, in assets/ch07/drag.html.

The drag/drop API lets you listen to drop events, which can respond to dropped files and other elements. This is where we start to see some of the drag/drop API craziness; for the drop event to fire at all, you have to cancel the defaults of both the dragover and the dragenter events! For example, here’s how to cancel the two events:

var element = $("#dropzone");

element.bind("dragenter", function(e){
  // Cancel event
  e.stopPropagation();
  e.preventDefault();
});

element.bind("dragover", function(e){
  // Set the cursor
  e.originalEvent.dataTransfer.dropEffect = "copy";

  // Cancel event
  e.stopPropagation();
  e.preventDefault();
});

You can also set a dropEffect—i.e., the cursor appearance—in the dragover event, as demonstrated above. By listening to the dragenter and dragleave events and toggling classes for the targeted element, you can give a visual indication to users that a certain area accepts dropped files.

Only once we’ve canceled dragenter and dragover’s events can we start listening to drop events. The drop event will trigger when a dragged element or file is dropped over the target element. The drop event’s dataTransfer object has a files attribute, which returns a FileList of all dropped files:

element.bind("drop", function(event){
  // Cancel redirection
  event.stopPropagation();
  event.preventDefault();

  event = event.originalEvent;

  // Access dragged files
  var files = event.dataTransfer.files;

  for (var i=0; i < files.length; i++)
    alert("Dropped " + files[i].name);
});

You can access data other than files using the dataTransfer.getData() function, passing the format you support. If that format isn’t available, the function will just return undefined.

var text = event.dataTransfer.getData("Text");

The dataTransfer object has a read-only types attribute, which returns a DOMStringList (essentially an array) of the mime formats that were set on the dragstart event. Additionally, if any files are being dragged, one of the types will be the string "Files".

var dt = event.dataTransfer
for (var i=0; i < dt.types.length; i++)
  console.log( dt.types[i], dt.getData(dt.types[i]) );

See the full drop example in assets/ch07/drop.html.

By default, dragging a file onto a web page makes the browser navigate to that file. We want to prevent that behavior because we don’t want users navigating away from our web application if they miss the drop area. This is easily accomplished—just cancel the body’s dragover event.

$("body").bind("dragover", function(e){
  e.stopPropagation();
  e.preventDefault();
  return false;
});

There are two events associated with copying, and two events with cutting:

As the name suggests, beforecopy and beforecut are triggered before any clipboard operations, allowing you to cancel them if necessary. When the user copies some selected text, the copy event fires, giving you a clipboardData object that can be used to set custom clipboard data. Like the dataTransfer object, clipboardData has a setData() function, which takes a mime format and string value. If you’re planning on calling this function, you should cancel the original copy event, preventing the default action.

Rather than on the event, IE sets the clipboardData object on window. You’ll need to check to see whether the object is present on the event, and if not, whether it’s present on the window.

Firefox will actually fire the copy event, but it won’t give you access to the clipboardData object. Chrome will give you the object, but it will ignore any data you set on it.

$("textarea").bind("copy", function(event){
  event.stopPropagation();
  event.preventDefault();

  var cd = event.originalEvent.clipboardData;

  // For IE
  if ( !cd ) cd = window.clipboardData;

  // For Firefox
  if ( !cd ) return;

  cd.setData("text/plain", $(this).text());
});

At the rate browsers are innovating, it’s quite likely support will be standardized soon. If you want to add copy/paste support to your application, you should take a look at the current situation yourself.

There are two events associated with pasting, beforepaste and paste. The paste event is triggered when the user initiates a paste, but before any data has been pasted. Again, different browsers have different implementations. Chrome triggers the event, even if no element has focus. Both IE and Safari require an actively focused element.

The API is very similar to the drop event API. The event has a clipboardData property, which gives you access to the pasted data using the getData() function, passing in a mime format. Unfortunately, from my tests, the types property is always null, so you can’t see which mime types are available on the clipboard data. Unless you cancel the event, the paste process will carry on as normal, and the data will be pasted into the focused element:

$("textarea").bind("paste", function(event){
  event.stopPropagation();
  event.preventDefault();

  event = event.originalEvent;

  var cd = event.clipboardData;

  // For IE
  if ( !cd ) cd = window.clipboardData;

  // For Firefox
  if ( !cd ) return;

  $("#result").text(cd.getData("text/plain"));

  // Safari event support file pasting
  var files = cd.files;
});

The nightly versions of WebKit give you access to a files property on clipboardData, allowing you to support file pasting into your application. I expect other browsers will follow suit once the specification is standardized.

So, is there any possibility of getting this to work cross-browser? Well, yes, there are actually a few workarounds. Cappuccino, for example, bypasses the oncopy family of events completely, and simply captures key inputs. When the key combination Command/Ctrl + v is detected, it then focuses a hidden input field, which gets filled with the pasted data. This works in every browser, but obviously for pastes initiated by the keyboard only—not the menu.

Sometimes it’s preferable to read a slice of the file into memory, rather than the entire thing. The HTML5 file APIs conveniently support a slice() function. This takes a starting byte as the first argument, and a byte offset (or slice length) as its second. It returns a Blob object, which we can interchange with methods that support the File object, such as FileReader. For example, we could buffer the file reading like this:

var bufferSize = 1024;
var pos = 0;

var onload = function(e){
  console.log("Read: ", e.target.result);
};

var onerror = function(e){
  console.log("Error!", e);
};

while (pos < file.size) {
  var blob = file.slice(pos, bufferSize);

  var reader = new FileReader();
  reader.onload  = onload;
  reader.onerror = onerror;
  reader.readAsText(blob);

  pos += bufferSize;
}

As you can see above, you can use a FileReader instance only once; after that, you’ll need to instantiate a new one.

You can check out the full example in assets/ch07/slices.html. One thing to watch out for is that the file can’t be read if the sandbox is local. In other words, if slices.html is being read from the disk, rather than hosted, the read will fail and the onerror event will be triggered.

The XHR Level 2 specification adds support for progress events, both for download and upload requests. This allows for a real-time file upload progress bar, giving users an estimated duration before the upload is complete.

To listen to the progress event on the download request, add it directly on the XHR instance:

var req = new XMLHttpRequest();

req.addEventListener("progress", updateProgress, false);
req.addEventListener("load", transferComplete, false);
req.open();

For the upload progress event, add it to the upload attribute of the XHR instance:

var req = new XMLHttpRequest();

req.upload.addEventListener("progress", updateProgress, false);
req.upload.addEventListener("load", transferComplete, false);
req.open();

The load event will fire once the upload request has completed, but before the server has issued a response. We can add it to jQuery because the XHR object and settings are passed to the beforeSend callback. The full example, including custom headers, looks like this:

$.ajax({
  url: "http://example.com",
  type: "POST",
  success: function(){ /* ... */ },
  processData: false,
  dataType: "multipart/form-data",

  beforeSend: function(xhr, settings){
    var upload = xhr.upload;

    if (settings.progress)
      upload.addEventListener("progress", settings.progress, false);

    if (settings.load)
      upload.addEventListener("load", settings.load, false);

    var fd = new FormData;

    for (var key in settings.data)
      fd.append(key, settings.data[key]);

    settings.data = fd;
  },

  data: file
});

The progress event contains the position of the upload (that is, how many bytes have uploaded) and the total (the size of the upload request in bytes). You can use these two properties to calculate a progress percentage:

var progress = function(event){
  var percentage = Math.round((event.position / event.total) * 100);
  // Set progress bar
}

In fact, the event has a timestamp, so if you record the time you started the upload, you can create a rudimentary estimated time of completion (ETA):

var startStamp = new Date();
var progress = function(e){
  var lapsed = startStamp - e.timeStamp;
  var eta    = lapsed * e.total / e.position - lapsed;
};

However, this estimation is unlikely to be accurate with smaller (and therefore quicker) uploads. In my opinion, it’s only worth showing an ETA if the upload will take longer than four minutes or so. A percentage bar is usually sufficient, as it gives users a clear and visual indication of how much longer an upload will take.

We want users to be able to drag and drop files onto the #drop element, so let’s turn it into a drop area. We need to bind to the drop event, canceling it and retrieving any dropped files, which are then passed to the uploadFile() function:

var view = $("#drop");
view.dropArea();

view.bind("drop", function(e){ 
  e.stopPropagation();
  e.preventDefault();

  var files = e.originalEvent.dataTransfer.files;
  for ( var i = 0; i < files.length; i++)
    uploadFile(files[i]);

  return false;
});

And now for the uploadFile() function—where the magic happens. We’re going use the $.upload() function in jquery.upload.js to send an Ajax upload request to the server. We’ll listen to progress events on the request and update a jQuery UI progress bar. Once the upload is complete, we’ll notify the user and remove the element:

var uploadFile = function(file){
  var element = $("<div />");
  element.text(file.fileName);

  var bar = $("<div />");
  element.append(bar);
  $("#progress").append(element);

  var onProgress = function(e){
    var per = Math.round((e.position / e.total) * 100);
    bar.progressbar({value: per});
  };

  var onSuccess = function(){
    element.text("Complete");
    element.delay(1000).fade();
  };

  $.upload("/uploads", file, {upload: {progress: onProgress}, success: onSuccess});
};

That’s pretty straightforward! To see the full example, check out assets/ch07/dragdropupload.html.