diff --git a/files/en-us/web/api/xmlhttprequest/send/index.md b/files/en-us/web/api/xmlhttprequest/send/index.md index 59f6ea7624f1578..5ee79413da9ad9e 100644 --- a/files/en-us/web/api/xmlhttprequest/send/index.md +++ b/files/en-us/web/api/xmlhttprequest/send/index.md @@ -81,7 +81,7 @@ xhr.send(null); const xhr = new XMLHttpRequest(); xhr.open("POST", '/server', true); -//Send the proper header information along with the request +// Send the proper header information along with the request xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded"); xhr.onreadystatechange = () => { // Call a function when the state changes. diff --git a/files/en-us/web/api/xmlhttprequest/upload/index.md b/files/en-us/web/api/xmlhttprequest/upload/index.md index 3badf319ada5854..b6f784b8ed6b05a 100644 --- a/files/en-us/web/api/xmlhttprequest/upload/index.md +++ b/files/en-us/web/api/xmlhttprequest/upload/index.md @@ -26,29 +26,29 @@ The following events can be triggered on an upload object and used to monitor th - {{domxref("XMLHttpRequest/loadstart_event", "loadstart")}} + {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}} The upload has begun. - {{domxref("XMLHttpRequest/progress_event", "progress")}} + {{domxref("XMLHttpRequestUpload/progress_event", "progress")}} Periodically delivered to indicate the amount of progress made so far. - {{domxref("XMLHttpRequest/abort_event", "abort")}} + {{domxref("XMLHttpRequestUpload/abort_event", "abort")}} The upload operation was aborted. - {{domxref("XMLHttpRequest/error_event", "error")}} + {{domxref("XMLHttpRequestUpload/error_event", "error")}} The upload failed due to an error. - {{domxref("XMLHttpRequest/load_event", "load")}} + {{domxref("XMLHttpRequestUpload/load_event", "load")}} The upload completed successfully. - {{domxref("XMLHttpRequest/timeout_event", "timeout")}} + {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}} The upload timed out because a reply did not arrive within the time interval specified by the @@ -56,7 +56,7 @@ The following events can be triggered on an upload object and used to monitor th - {{domxref("XMLHttpRequest/loadend_event", "loadend")}} + {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}} The upload finished. This event does not differentiate between success or failure, and is sent at the end of the upload regardless of the @@ -79,4 +79,4 @@ The following events can be triggered on an upload object and used to monitor th ## See also - [Using XMLHttpRequest](/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest) -- [File and Directory Entries API](/en-US/docs/Web/API/File_and_Directory_Entries_API) +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequesteventtarget/index.md b/files/en-us/web/api/xmlhttprequesteventtarget/index.md index 09151fa925a4be5..5effc4710096cfd 100644 --- a/files/en-us/web/api/xmlhttprequesteventtarget/index.md +++ b/files/en-us/web/api/xmlhttprequesteventtarget/index.md @@ -23,6 +23,7 @@ The following events are made available to {{domxref("XMLHttpRequest")}}: - {{domxref("XMLHttpRequest/loadend_event", "loadend")}} - {{domxref("XMLHttpRequest/loadstart_event", "loadstart")}} - {{domxref("XMLHttpRequest/progress_event", "progress")}} +- {{domxref("XMLHttpRequest/readystatechange_event", "readystatechange")}} - {{domxref("XMLHttpRequest/timeout_event", "timeout")}} ## Inheritance for `XMLHttpRequestUpload` diff --git a/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md b/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md new file mode 100644 index 000000000000000..94e5bd8cbe897a7 --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/abort_event/index.md @@ -0,0 +1,66 @@ +--- +title: "XMLHttpRequestUpload: abort event" +slug: Web/API/XMLHttpRequestUpload/abort_event +page-type: web-api-event +browser-compat: api.XMLHttpRequestUpload.abort_event +--- + +{{APIRef}} + +The `abort` event is fired at {{domxref("XMLHttpRequestUpload")}} when a request has been aborted, for example because the program called {{domxref("XMLHttpRequest.abort()")}}. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('abort', (event) => { }) + +onabort = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +## Examples + +### Using the `abort` event + +You can use the `abort` event to stop the upload before it finishes. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +```js +// In case of an abort we hide the progress bar +// Note that this event can be listened to on the xhr object too +function errorAction(event) { + progressBar.classList.remove("visible"); + log.textContent = `Upload failed: ${event.type}`; +} +xhr.upload.addEventListener("abort", errorAction); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}}, {{domxref("XMLHttpRequestUpload/load_event", "load")}}, {{domxref("XMLHttpRequestUpload/progress_event", "progress")}}, {{domxref("XMLHttpRequestUpload/error_event", "error")}}, {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}}, {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}} +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/error_event/index.md b/files/en-us/web/api/xmlhttprequestupload/error_event/index.md new file mode 100644 index 000000000000000..79d01ecef35196d --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/error_event/index.md @@ -0,0 +1,66 @@ +--- +title: "XMLHttpRequestUpload: error event" +slug: Web/API/XMLHttpRequestUpload/error_event +page-type: web-api-event +browser-compat: api.XMLHttpRequestUpload.error_event +--- + +{{APIRef}} + +The `error` event is fired when the request encountered an error. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('error', (event) => { }) + +onerror = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +## Examples + +### Using the `error` event + +You can use the `error` event to detect a problem with the upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +```js +// In case of an error we hide the progress bar +// Note that this event can be listened to on the xhr object too +function errorAction(event) { + progressBar.classList.remove("visible"); + log.textContent = `Upload failed: ${event.type}`; +} +xhr.upload.addEventListener("error", errorAction); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}}, {{domxref("XMLHttpRequestUpload/load_event", "load")}}, {{domxref("XMLHttpRequestUpload/progress_event", "progress")}}, {{domxref("XMLHttpRequestUpload/abort_event", "abort")}}, {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}}, {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}} +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/index.md b/files/en-us/web/api/xmlhttprequestupload/index.md new file mode 100644 index 000000000000000..b973ddde1a0bd59 --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/index.md @@ -0,0 +1,199 @@ +--- +title: XMLHttpRequestUpload +slug: Web/API/XMLHttpRequestUpload +page-type: web-api-interface +browser-compat: api.XMLHttpRequestUpload +--- + +{{APIRef("XMLHttpRequest")}} + +The **`XMLHttpRequestUpload`** interface represents the upload process for a specific {{domxref("XMLHttpRequest")}}. It is an _opaque_ object that represents the underlying, browser-dependant, upload process. It is {{domxref("XMLHttpRequestEventTarget")}} and is can be obtained by calling {{domxref("XMLHttpRequest.upload")}}. + +{{AvailableInWorkers("notservice")}} + +{{InheritanceDiagram}} + +## Instance properties + +_This interface has no specific property, but inherits the properties of {{domxref("XMLHttpRequestEventTarget")}} and of {{domxref("EventTarget")}}._ + +## Instance methods + +_This interface has no specific method, but inherits the methods of {{domxref("XMLHttpRequestEventTarget")}} and of {{domxref("EventTarget")}}._ + +## Events + +- {{domxref("XMLHttpRequestUpload/abort_event", "abort")}} + - : Fired when a request has been aborted, for example because the program called {{domxref("XMLHttpRequest.abort()")}}. + Also available via the `onabort` event handler property. +- {{domxref("XMLHttpRequestUpload/error_event", "error")}} + - : Fired when the request encountered an error. + Also available via the `onerror` event handler property. +- {{domxref("XMLHttpRequestUpload/load_event", "load")}} + - : Fired when a request transaction completes successfully. + Also available via the `onload` event handler property. +- {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}} + - : Fired when a request has completed, whether successfully (after {{domxref("XMLHttpRequest/load_event", "load")}}) or unsuccessfully (after {{domxref("XMLHttpRequestUpload/abort_event", "abort")}} or {{domxref("XMLHttpRequest/error_event", "error")}}). + Also available via the `onloadend` event handler property. +- {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}} + - : Fired when a request has started to load data. + Also available via the `onloadstart` event handler property. +- {{domxref("XMLHttpRequestUpload/progress_event", "progress")}} + - : Fired periodically when a request receives more data. + Also available via the `onprogress` event handler property. +- {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}} + - : Fired when progress is terminated due to preset time expiring. + Also available via the `ontimeout` event handler property. + +## Examples + +### Uploading a file with a timeout + +This allows you to upload a file to a server; it displays a progress bar while the upload is happening as well as a message with the progress and the results, success or failure. An abort button allows to stop an upload. + +#### HTML + +```html + + + + + + XMLHttpRequestUpload test + + + + +
+

Upload a file

+

+ +

+

+ +

+

+ +

+

+ +

+
+ + +``` + +#### CSS + +```css +body { + background-color: lightblue; +} + +main { + margin: 50px auto; + text-align: center; +} + +#file { + display: none; +} + +label[for="file"] { + background-color: lightgrey; + padding: 10px 10px; +} + +progress { + display: none; +} + +progress.visible { + display: inline; +} +``` + +#### JavaScript + +```js +addEventListener("DOMContentLoaded", () => { + const fileInput = document.getElementById("file"); + const progressBar = document.querySelector("progress"); + const log = document.querySelector("output"); + const abortButton = document.getElementById("abort"); + + fileInput.addEventListener("change", () => { + const xhr = new XMLHttpRequest(); + xhr.timeout = 2000; // 2 seconds + + // Link abort button + abortButton.addEventListener( + "click", + () => { + xhr.abort(); + }, + { once: true } + ); + + // When the upload starts, we display the progress bar + xhr.upload.addEventListener("loadstart", (event) => { + progressBar.classList.add("visible"); + progressBar.value = 0; + progressBar.max = event.total; + log.textContent = "Uploading (0%)…"; + abortButton.disabled = false; + }); + + // Each time a progress event is received, we update the bar + xhr.upload.addEventListener("progress", (event) => { + progressBar.value = event.loaded; + log.textContent = `Uploading (${( + (event.loaded / event.total) * + 100 + ).toFixed(2)}%)…`; + }); + + // When the upload is finished, we hide the progress bar. + xhr.upload.addEventListener("loadend", (event) => { + progressBar.classList.remove("visible"); + if (event.loaded !== 0) { + log.textContent = "Upload finished."; + } + abortButton.disabled = true; + }); + + // In case of an error, an abort, or a timeout, we hide the progress bar + // Note that these events can be listened to on the xhr object too + function errorAction(event) { + progressBar.classList.remove("visible"); + log.textContent = `Upload failed: ${event.type}`; + } + xhr.upload.addEventListener("error", errorAction); + xhr.upload.addEventListener("abort", errorAction); + xhr.upload.addEventListener("timeout", errorAction); + + // Build the payload + const fileData = new FormData(); + fileData.append("file", fileInput.files[0]); + + // Theoretically, event listeners could be set after the open() call + // but browsers are buggy here + xhr.open("POST", "upload_test.php", true); + + // Note that the event listener must be set before sending (as it is a preflighted request) + xhr.send(fileData); + }); +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("XMLHttpRequest")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/load_event/index.md b/files/en-us/web/api/xmlhttprequestupload/load_event/index.md new file mode 100644 index 000000000000000..70f6b2c59317d97 --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/load_event/index.md @@ -0,0 +1,65 @@ +--- +title: "XMLHttpRequestUpload: load event" +slug: Web/API/XMLHttpRequestUpload/load_event +page-type: web-api-event +browser-compat: api.XMLHttpRequest.load_event +--- + +{{APIRef}} + +The `load` event is fired when an {{domxref("XMLHttpRequestUpload")}} transaction completes successfully. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('load', (event) => { }) + +onload = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +### Examples + +## Using the `load` event + +You can use the `load` event to detect the successful termination of an upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +```js +// When the upload is finished, we hide the progress bar. +xhr.upload.addEventListener("load", (event) => { + progressBar.classList.remove("visible"); + log.textContent = "Upload finished."; + abortButton.disabled = true; +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}}, {{domxref("XMLHttpRequestUpload/progress_event", "progress")}}, {{domxref("XMLHttpRequestUpload/error_event", "error")}}, {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}}, {{domxref("XMLHttpRequestUpload/abort_event", "abort")}}, {{domxref("XMLHttpRequestUpload/timeout_event", "timoeout")}} +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md b/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md new file mode 100644 index 000000000000000..caa659b90d8e440 --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/loadend_event/index.md @@ -0,0 +1,69 @@ +--- +title: "XMLHttpRequestUpload: loadend event" +slug: Web/API/XMLHttpRequestUpload/loadend_event +page-type: web-api-event +browser-compat: api.XMLHttpRequestUpload.loadend_event +--- + +{{APIRef}} + +The **`loadend`** event is fired when a request has completed, whether successfully (after {{domxref("XMLHttpRequestUpload/load_event", "load")}}) or unsuccessfully (after {{domxref("XMLHttpRequestUpload/abort_event", "abort")}} or {{domxref("XMLHttpRequestUpload/error_event", "error")}}). + +The `loadend` event is also sent when the request has been interrupted (by a {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}}, an {{domxref("XMLHttpRequestUpload/abort_event", "abort")}}, or an {{domxref("XMLHttpRequestUpload/error_event", "error")}}). In such cases, both the `loaded` and `total` value of the event will be 0. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('loadend', (event) => { }) + +onloadend = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +## Examples + +## Using the `loadend` event + +You can use the `loadend` event to detect the (successful or not) termination of an upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +```js +// When the upload is finished, we hide the progress bar. +xhr.upload.addEventListener("loadend", (event) => { + progressBar.classList.remove("visible"); + if (event.loaded !== 0) { // Successful termination + log.textContent = "Upload finished."; + } + abortButton.disabled = true; +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}}, {{domxref("XMLHttpRequestUpload/progress_event", "progress")}}, {{domxref("XMLHttpRequestUpload/error_event", "error")}}, {{domxref("XMLHttpRequestUpload/load_event", "load")}}, {{domxref("XMLHttpRequestUpload/abort_event", "abort")}}, {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}} +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md b/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md new file mode 100644 index 000000000000000..1f1ede49bf522cc --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/loadstart_event/index.md @@ -0,0 +1,67 @@ +--- +title: "XMLHttpRequestUpload: loadstart event" +slug: Web/API/XMLHttpRequestUpload/loadstart_event +page-type: web-api-event +browser-compat: api.XMLHttpRequestUpload.loadstart_event +--- + +{{APIRef}} + +The **`loadstart`** event is fired when a request has started to load data. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('loadstart', (event) => { }) + +onloadstart = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +## Examples + +## Using the `loadstart` event + +You can use the `loadstart` event to detect the beginning of an upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +```js +// When the upload starts, we display the progress bar +xhr.upload.addEventListener("loadstart", (event) => { + progressBar.classList.add("visible"); + progressBar.value = 0; + progressBar.max = event.total; + log.textContent = "Uploading (0%)…"; + abortButton.disabled = false; +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/load_event", "load")}}, {{domxref("XMLHttpRequestUpload/progress_event", "progress")}}, {{domxref("XMLHttpRequestUpload/error_event", "error")}}, {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}}, {{domxref("XMLHttpRequestUpload/abort_event", "abort")}}, {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}} +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md b/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md new file mode 100644 index 000000000000000..52fa00b0e8bf10f --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/progress_event/index.md @@ -0,0 +1,69 @@ +--- +title: "XMLHttpRequestUpload: progress event" +slug: Web/API/XMLHttpRequestUpload/progress_event +page-type: web-api-event +browser-compat: api.XMLHttpRequestUpload.progress_event +--- + +{{APIRef}} + +The **`progress`** event is fired periodically when a request receives more data. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('progress', (event) => { }) + +onprogress = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +## Examples + +## Using the `progress` event + +You can use the `progress` event to get info about the progress of a lengthy upload. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +```js +// Each time a progress event is received we update the progress bar +// and the progress message +xhr.upload.addEventListener("progress", (event) => { + progressBar.value = event.loaded; // Update the progress bar + log.textContent = `Uploading (${( + (event.loaded / event.total) * + 100 + ).toFixed(2)}%)…`; +}); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}}, {{domxref("XMLHttpRequestUpload/load_event", "load")}}, {{domxref("XMLHttpRequestUpload/error_event", "error")}}, {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}}, {{domxref("XMLHttpRequestUpload/timeout_event", "timeout")}}, {{domxref("XMLHttpRequestUpload/abort_event", "abort")}} +- [Monitoring progress](/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest#monitoring_progress) +- {{domxref("XMLHttpRequestUpload")}} diff --git a/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md b/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md new file mode 100644 index 000000000000000..b31d210c7d589c1 --- /dev/null +++ b/files/en-us/web/api/xmlhttprequestupload/timeout_event/index.md @@ -0,0 +1,69 @@ +--- +title: 'XMLHttpRequestUpload: timeout event' +slug: Web/API/XMLHttpRequestUpload/timeout_event +page-type: web-api-event +browser-compat: api.XMLHttpRequestUpload.timeout_event +--- + +{{APIRef}} + +The **`timeout`** event is fired when progression is terminated due to preset time expiring. + +## Syntax + +Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property. + +```js +addEventListener('timeout', (event) => { }) + +ontimeout = (event) => { } +``` + +## Event type + +A {{domxref("ProgressEvent")}}. Inherits from {{domxref("Event")}}. + +{{InheritanceDiagram("ProgressEvent")}} + +## Event properties + +_In addition to the properties listed below, properties from the parent interface, {{domxref("Event")}}, are available._ + +- {{domxref("ProgressEvent.lengthComputable", "lengthComputable")}} {{ReadOnlyInline}} + - : A boolean flag indicating if the total work to be done, and the amount of work already done, by the underlying process is calculable. In other words, it tells if the progress is measurable or not. +- {{domxref("ProgressEvent.loaded", "loaded")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer value indicating the amount of work already performed by the underlying process. The ratio of work done can be calculated by dividing `total` by the value of this property. When downloading a resource using HTTP, this only counts the body of the HTTP message, and doesn't include headers and other overhead. +- {{domxref("ProgressEvent.total", "total")}} {{ReadOnlyInline}} + - : A 64-bit unsigned integer representing the total amount of work that the underlying process is in the progress of performing. When downloading a resource using HTTP, this is the `Content-Length` (the size of the body of the message), and doesn't include the headers and other overhead. + +## Examples + +### Using the `timeout` event + +You can use the `timeout` event to detect an upload that stopped because it was too slow. For a complete code example that uploads a file and displays a progress bar, see the main {{domxref("XMLHttpRequestUpload")}} page. + +The timeout is set on the {{domxref("XMLHttpRequest")}} object using the {{domxref("XMLHttpRequest.timeout")}} property. + +```js +// In case of an timeout we hide the progress bar +// Note that this event can be listened to on the xhr object too +function errorAction(event) { + progressBar.classList.remove("visible"); + log.textContent = `Upload failed: ${event.type}`; +} +xhr.upload.addEventListener("timeout", errorAction); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Related events: {{domxref("XMLHttpRequestUpload/loadstart_event", "loadstart")}}, {{domxref("XMLHttpRequestUpload/load_event", "load")}}, {{domxref("XMLHttpRequestUpload/progress_event", "progress")}}, {{domxref("XMLHttpRequestUpload/error_event", "error")}}, {{domxref("XMLHttpRequestUpload/loadend_event", "loadend")}}, {{domxref("XMLHttpRequestUpload/abort_event", "abort")}} +- {{domxref("XMLHttpRequestUpload")}} +- {{domxref("XMLHttpRequest.timeout")}}