Morph MORPH
SIGN IN SIGN UP
javascript-tutorial / en.javascript.info UNCLAIMED

Modern JavaScript Tutorial

25221 0 0 HTML
Normal View History Raw
updates
2019-07-03 17:19:00 +03:00
# FormData
minor
2019-08-10 00:08:04 +03:00
This chapter is about sending HTML forms: with or without files, with additional fields and so on.
[FormData](https://xhr.spec.whatwg.org/#interface-formdata) objects can help with that. As you might have guessed, it's the object to represent HTML form data.
updates
2019-07-03 17:19:00 +03:00
The constructor is:
```js
let formData = new FormData([form]);
```
minor
2019-08-10 00:08:04 +03:00
If HTML `form` element is provided, it automatically captures its fields.
fix typo
2020-03-29 10:23:34 +08:00
The special thing about `FormData` is that network methods, such as `fetch`, can accept a `FormData` object as a body. It's encoded and sent out with `Content-Type: multipart/form-data`.
updates
2019-07-03 17:19:00 +03:00
minor
2019-08-10 00:08:04 +03:00
From the server point of view, that looks like a usual form submission.
updates
2019-07-03 17:19:00 +03:00
## Sending a simple form
Let's send a simple form first.
As you can see, that's almost one-liner:
```html run autorun
<form id="formElem">
<input type="text" name="name" value="John">
<input type="text" name="surname" value="Smith">
<input type="submit">
</form>
<script>
formElem.onsubmit = async (e) => {
e.preventDefault();
let response = await fetch('/article/formdata/post/user', {
method: 'POST',
*!*
body: new FormData(formElem)
*/!*
});
let result = await response.json();
alert(result.message);
};
</script>
```
minor
2019-08-10 00:08:04 +03:00
In this example, the server code is not presented, as it's beyound our scope. The server accepts the POST request and replies "User saved".
minor
2019-07-03 17:32:47 +03:00
updates
2019-07-03 17:19:00 +03:00
## FormData Methods
We can modify fields in `FormData` with methods:
- `formData.append(name, value)` - add a form field with the given `name` and `value`,
Fix: typos
2019-11-19 20:49:32 +09:00
- `formData.append(name, blob, fileName)` - add a field as if it were `<input type="file">`, the third argument `fileName` sets file name (not form field name), as it were a name of the file in user's filesystem,
updates
2019-07-03 17:19:00 +03:00
- `formData.delete(name)` - remove the field with the given `name`,
- `formData.get(name)` - get the value of the field with the given `name`,
- `formData.has(name)` - if there exists a field with the given `name`, returns `true`, otherwise `false`
A form is technically allowed to have many fields with the same `name`, so multiple calls to `append` add more same-named fields.
Fix: typos
2019-11-19 20:49:32 +09:00
There's also method `set`, with the same syntax as `append`. The difference is that `.set` removes all fields with the given `name`, and then appends a new field. So it makes sure there's only one field with such `name`, the rest is just like `append`:
updates
2019-07-03 17:19:00 +03:00
- `formData.set(name, value)`,
- `formData.set(name, blob, fileName)`.
Also we can iterate over formData fields using `for..of` loop:
```js run
let formData = new FormData();
formData.append('key1', 'value1');
formData.append('key2', 'value2');
// List key/value pairs
for(let [name, value] of formData) {
alert(`${name} = ${value}`); // key1=value1, then key2=value2
}
```
## Sending a form with a file
fix typo
2020-03-29 10:23:34 +08:00
The form is always sent as `Content-Type: multipart/form-data`, this encoding allows to send files. So, `<input type="file">` fields are sent also, similar to a usual form submission.
updates
2019-07-03 17:19:00 +03:00
Here's an example with such form:
```html run autorun
<form id="formElem">
<input type="text" name="firstName" value="John">
Picture: <input type="file" name="picture" accept="image/*">
<input type="submit">
</form>
<script>
formElem.onsubmit = async (e) => {
e.preventDefault();
let response = await fetch('/article/formdata/post/user-avatar', {
method: 'POST',
*!*
body: new FormData(formElem)
*/!*
});
let result = await response.json();
alert(result.message);
};
</script>
```
minor
2019-07-09 16:03:21 +03:00
## Sending a form with Blob data
updates
2019-07-03 17:19:00 +03:00
minor
2019-08-10 00:08:04 +03:00
As we've seen in the chapter <info:fetch>, it's easy to send dynamically generated binary data e.g. an image, as `Blob`. We can supply it directly as `fetch` parameter `body`.
updates
2019-07-03 17:19:00 +03:00
minor
2019-07-09 16:03:21 +03:00
In practice though, it's often convenient to send an image not separately, but as a part of the form, with additional fields, such as "name" and other metadata.
updates
2019-07-03 17:19:00 +03:00
Also, servers are usually more suited to accept multipart-encoded forms, rather than raw binary data.
minor
2019-08-10 00:08:04 +03:00
This example submits an image from `<canvas>`, along with some other fields, as a form, using `FormData`:
updates
2019-07-03 17:19:00 +03:00
```html run autorun height="90"
<body style="margin:0">
<canvas id="canvasElem" width="100" height="80" style="border:1px solid"></canvas>
<input type="button" value="Submit" onclick="submit()">
<script>
canvasElem.onmousemove = function(e) {
let ctx = canvasElem.getContext('2d');
ctx.lineTo(e.clientX, e.clientY);
ctx.stroke();
};
async function submit() {
let imageBlob = await new Promise(resolve => canvasElem.toBlob(resolve, 'image/png'));
*!*
let formData = new FormData();
formData.append("firstName", "John");
formData.append("image", imageBlob, "image.png");
*/!*
let response = await fetch('/article/formdata/post/image-form', {
method: 'POST',
body: formData
});
let result = await response.json();
alert(result.message);
}
</script>
</body>
```
Please note how the image `Blob` is added:
```js
formData.append("image", imageBlob, "image.png");
```
minor
2019-08-10 00:08:04 +03:00
That's same as if there were `<input type="file" name="image">` in the form, and the visitor submitted a file named `"image.png"` (3rd argument) with the data `imageBlob` (2nd argument) from their filesystem.
The server reads form data and the file, as if it were a regular form submission.
updates
2019-07-03 17:19:00 +03:00
## Summary
minor
2019-07-09 16:03:21 +03:00
[FormData](https://xhr.spec.whatwg.org/#interface-formdata) objects are used to capture HTML form and submit it using `fetch` or another network method.
updates
2019-07-03 17:19:00 +03:00
minor
2019-08-10 00:08:04 +03:00
We can either create `new FormData(form)` from an HTML form, or create a object without a form at all, and then append fields with methods:
updates
2019-07-03 17:19:00 +03:00
- `formData.append(name, value)`
- `formData.append(name, blob, fileName)`
- `formData.set(name, value)`
- `formData.set(name, blob, fileName)`
minor
2019-08-10 00:08:04 +03:00
Let's note two peculiarities here:
1. The `set` method removes fields with the same name, `append` doesn't. That's the only difference between them.
updates
2019-07-03 17:19:00 +03:00
2. To send a file, 3-argument syntax is needed, the last argument is a file name, that normally is taken from user filesystem for `<input type="file">`.
Other methods are:
- `formData.delete(name)`
- `formData.get(name)`
- `formData.has(name)`
That's it!
Reference in New Issue Copy Permalink