This feature has landed in Mozilla Central (trunk) and only available with a Firefox Nightly Build for the time being.

XMLHttpRequest Level 2 (editor’s draft) adds support for the new FormData interface. FormData objects provide a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using the XMLHttpRequest send() method in “multipart/form-data” format.

Why FormData?

When you want to send complex data to a server from a web page (files, non-ASCII content), you must use the multipart/form-data content type. To set the content type in a <form>, you write:

This is what you usually do to upload a file.

Starting with Firefox 3.6, you can manipulate files with JavaScript (see File API), and maybe you want to send files using XMLHttpRequest. But if, for example, you want to reproduce this form, it’s really hard because you’ll have to create the multipart/form-data content yourself in JavaScript (see, for example, this code I wrote a while ago implementing a multipart/form-data: ugly and slow).

This is where FormData is useful: to reproduce the <form> submission mechanism in JavaScript

The FormData object

The FormData object lets you compile a set of key/value pairs to send using XMLHttpRequest. This object has only one method:

append(key, value);

where key is the name of your value, and where value can be a string or a file.

You can create a FormData object, append values and then send it through XMLHttpRequest. If you want to simulate the previous form, you write:

// aFile could be from an input type="file" or from a Dragged'n Dropped file
var formdata = new FormData();
formdata.append("nickname", "Foooobar");
formdata.append("website", "http://hacks.mozilla.org");
formdata.append("media", aFile);
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://foo.bar/upload.php");
xhr.send(formdata);

FormData and the <form> element

Firefox extends the HTML form element slightly, adding a getFormData() method that lets you fetch a form’s data as a FormData object. This is not yet part of the HTML standard, but is expected to be added to the specification at some point in the future (although possibly with a different name):

var formElement = document.getElementById("myFormElement");
var xhr = new XMLHttpRequest();
xhr.open("POST", "submitform.php");
xhr.send(formElement.getFormData());

You can also add data to the FormData object between retrieving it from a form and sending it, like this:

var formElement = document.getElementById("myFormElement");
formData = formElement.getFormData();
formData.append("serialnumber", serialNumber++);
xhr.send(formData);

This lets you augment the form’s data before sending it along, to include additional information that’s not necessarily user editable on the form.

Resources

• MDN: XMLHttpRequest FormData
• MDN: Using FormData
• W3C the FormData interface
• W3C the multipart/form-data content type
• Bug 546528 – Implement FormData