Update events on BackgroundFetchRegistration (#12851)

mdn · Feb 9, 2022 · 2dc84f4 · 2dc84f4
1 parent ebcdb22
commit 2dc84f4
Show file tree

Hide file tree

Showing 15 changed files with 99 additions and 79 deletions.
diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt
@@ -7248,6 +7248,7 @@
 /en-US/docs/Web/API/AudioParam.value	/en-US/docs/Web/API/AudioParam/value
 /en-US/docs/Web/API/AudioWorkletNode/AudioWorkletNode.parameters	/en-US/docs/Web/API/AudioWorkletNode/parameters
 /en-US/docs/Web/API/AudioWorkletNodeOptions	/en-US/docs/Web/API/AudioWorkletNode/AudioWorkletNode
+/en-US/docs/Web/API/BackgroundFetchRegistration/onprogress	/en-US/docs//Web/API/BackgroundFetchRegistration/progress_event
 /en-US/docs/Web/API/Barcode_Detector_API	/en-US/docs/Web/API/Barcode_Detection_API
 /en-US/docs/Web/API/BaseAudioContext/resume	/en-US/docs/Web/API/AudioContext/resume
 /en-US/docs/Web/API/BatteryManager.charging	/en-US/docs/Web/API/BatteryManager/charging

diff --git a/files/en-us/web/api/backgroundfetchregistration/abort/index.md b/files/en-us/web/api/backgroundfetchregistration/abort/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.abort
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`abort()`** method of the {{domxref("BackgroundFetchRegistration")}} interface aborts an active background fetch.
 

diff --git a/files/en-us/web/api/backgroundfetchregistration/downloaded/index.md b/files/en-us/web/api/backgroundfetchregistration/downloaded/index.md
@@ -9,10 +9,12 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.downloaded
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`downloaded`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns the size in bytes that has been downloaded, initially `0`.
 
+If the value of this property changes, the  [progress](/en-US/docs/Web/API/BackgroundFetchRegistration/progress_event) event is fired at the associated {{domxref("BackgroundFetchRegistration")}} object.
+
 ## Syntax
 
 ```js
@@ -25,7 +27,7 @@ A {{jsxref("number")}}.
 
 ## Examples
 
-Logging {{domxref("BackgroundFetchRegistration.downloaded")}} to the console returns the number of bytes downloaded.
+Logging this property to the console returns the number of bytes downloaded.
 
 ```js
 console.log(bgFetch.downloaded);

diff --git a/files/en-us/web/api/backgroundfetchregistration/downloadtotal/index.md b/files/en-us/web/api/backgroundfetchregistration/downloadtotal/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.downloadTotal
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`downloadTotal`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns the total size in bytes of this download. This is set when the background fetch was registered, or `0` if not set.
 
@@ -25,6 +25,12 @@ A {{jsxref("number")}}.
 
 ## Examples
 
+Logging this property to the console returns the total size in bytes of this download.
+
+```js
+console.log(bgFetch.downloadTotal);
+```
+
 ## Specifications
 
 {{Specifications}}

diff --git a/files/en-us/web/api/backgroundfetchregistration/failurereason/index.md b/files/en-us/web/api/backgroundfetchregistration/failurereason/index.md
@@ -9,10 +9,13 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.failureReason
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`failureReason`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns a string with a value that indicates a reason for a background fetch failure.
 
+If the value of this property changes, the  [progress](/en-US/docs/Web/API/BackgroundFetchRegistration/progress_event) event is fired at the associated {{domxref("BackgroundFetchRegistration")}} object.
+
+
 ## Syntax
 
 ```js
@@ -38,7 +41,7 @@ One of the following strings:
 
 ## Examples
 
-Logging {{domxref("BackgroundFetchRegistration.failureReason")}} to the console prints the reason the fetch failed, or an empty string if it was successful or has not yet completed.
+Logging this property to the console prints the reason the fetch failed, or an empty string if it was successful or has not yet completed.
 
 ```js
 console.log(bgFetch.failureReason);

diff --git a/files/en-us/web/api/backgroundfetchregistration/id/index.md b/files/en-us/web/api/backgroundfetchregistration/id/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.id
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`id`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns a copy of the background fetch's `ID`.
 
@@ -25,7 +25,7 @@ A {{domxref("DOMString","string")}}.
 
 ## Examples
 
-Logging the {{domxref("BackgroundFetchRegistration.id")}} to the console returns the `ID` set when registering the fetch. In this case, `"my-fetch"`.
+Logging the this part to the console returns the identifier set when registering the fetch. In this case, `"my-fetch"`.
 
 ```js
 console.log(bgFetch.id); // "my-fetch"

diff --git a/files/en-us/web/api/backgroundfetchregistration/index.md b/files/en-us/web/api/backgroundfetchregistration/index.md
@@ -8,7 +8,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`BackgroundFetchRegistration`** interface of the {{domxref('Background Fetch API','','',' ')}} represents an individual background fetch.
 
@@ -52,17 +52,6 @@ The following properties are available synchronously, as convenience properties
 - {{domxref("BackgroundFetchRegistration.recordsAvailable")}}{{ReadOnlyInline}}
   - : A {{jsxref("boolean")}} indicating whether the `recordsAvailable` flag is set.
 
-### Event handlers
-
-- {{domxref("BackgroundFetchRegistration.onprogress")}}
-
-  - : Fired when there is a change to any of the following properties:
-
-    - `uploaded`
-    - `downloaded`
-    - `result`
-    - `failureReason`
-
 ## Methods
 
 - {{domxref("BackgroundFetchRegistration.abort","BackgroundFetchRegistration.abort()")}}
@@ -72,6 +61,18 @@ The following properties are available synchronously, as convenience properties
 - {{domxref("BackgroundFetchRegistration.matchAll","BackgroundFetchRegistration.matchAll()")}}
   - : Returns a {{jsxref("Promise")}} that resolves with an array of {{domxref("BackgroundFetchRecord")}} objects containing requests and responses.
 
+## Events
+
+Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTarget/addEventListener) or by assigning an event listener to the `oneventname` property of this interface.
+
+- [`progress`](/en-US/docs/Web/API/BackgroundFetchRegistration/progress_event)
+
+  - : Fired when there is a change to any of the following properties:
+    {{domxref("BackgroundFetchRegistration.uploaded", "uploaded")}},
+    {{domxref("BackgroundFetchRegistration.downloaded", "downloaded")}},
+    {{domxref("BackgroundFetchRegistration.result", "result")}} or
+    {{domxref("BackgroundFetchRegistration.failureReason", "failureReason")}}.
+
 ## Examples
 
 The following code creates a `BackGroundFetchRegistration` as `bgFetch`, with an `id` of `"my-fetch"`.

diff --git a/files/en-us/web/api/backgroundfetchregistration/match/index.md b/files/en-us/web/api/backgroundfetchregistration/match/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.match
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`match()`** method of the {{domxref("BackgroundFetchRegistration")}} interface returns the first matching {{domxref("BackgroundFetchRecord")}}.
 

diff --git a/files/en-us/web/api/backgroundfetchregistration/matchall/index.md b/files/en-us/web/api/backgroundfetchregistration/matchall/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.matchAll
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`matchAll()`** method of the {{domxref("BackgroundFetchRegistration")}} interface returns an array of matching {{domxref("BackgroundFetchRecord")}} objects.
 

diff --git a/files/en-us/web/api/backgroundfetchregistration/onprogress/index.md b/files/en-us/web/api/backgroundfetchregistration/onprogress/index.md
diff --git a/files/en-us/web/api/backgroundfetchregistration/progress_event/index.md b/files/en-us/web/api/backgroundfetchregistration/progress_event/index.md
@@ -0,0 +1,53 @@
+---
+title: 'BackgroundFetchRegistration: progress event'
+slug: Web/API/BackgroundFetchRegistration/progress_event
+tags:
+  - progress
+  - API
+  - Reference
+  - Event
+browser-compat: api.BackgroundFetchRegistration.progress_event
+---
+{{APIRef("Background Fetch API")}}
+
+The **`progress`** event of the {{domxref("BackgroundFetchRegistration")}} interface thrown when the associated background fetch progresses.
+
+Practically, this event is fired when any of the following properties will return a new value:
+
+- {{domxref("BackgroundFetchRegistration.uploaded", "uploaded")}},
+- {{domxref("BackgroundFetchRegistration.downloaded", "downloaded")}},
+- {{domxref("BackgroundFetchRegistration.result", "result")}}, or
+- {{domxref("BackgroundFetchRegistration.failureReason", "failureReason")}}.
+
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set the `onprogress` event property on the relevent {{domxref("BackgroundFetchRegistration")}} object.
+
+```js
+addEventListener('progress', event => { })
+onprogress = event => { }
+```
+
+## Event type
+
+A generic {{domxref("Event")}} with no added properties.
+
+## Example
+
+The following example demonstrates how to log the progress of a download. The code first checks that a `downloadTotal` was provided when the background fetch was registered. This is then used to calculate the percentage, based on the `downloaded` property.
+
+```js
+bgFetch.addEventListener('progress', () => {
+  if (!bgFetch.downloadTotal) return;
+  const percent = Math.round(bgFetch.downloaded / bgFetch.downloadTotal * 100);
+  console.log(`Download progress: ${percent}%`);
+});
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/web/api/backgroundfetchregistration/recordsavailable/index.md b/files/en-us/web/api/backgroundfetchregistration/recordsavailable/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.recordsAvailable
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`recordsAvailable`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns `true` if there are requests and responses to be accessed. If this returns false then {{domxref("BackgroundFetchRegistration.match()","match()")}} and {{domxref("BackgroundFetchRegistration.matchAll()","matchAll()")}} can't be used.
 
@@ -25,7 +25,7 @@ A {{jsxref("boolean")}}.
 
 ## Examples
 
-Logging {{domxref("BackgroundFetchRegistration.recordsAvailable")}} to the console returns `true` or `false` to indicate if there are records.
+Logging this property to the console returns `true` or `false` to indicate if there are records.
 
 ```js
 console.log(bgFetch.recordsAvailable);

diff --git a/files/en-us/web/api/backgroundfetchregistration/result/index.md b/files/en-us/web/api/backgroundfetchregistration/result/index.md
@@ -9,10 +9,12 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.result
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`result`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns a string indicating whether the background fetch was successful or failed.
 
+If the value of this property changes, the  [progress](/en-US/docs/Web/API/BackgroundFetchRegistration/progress_event) event is fired at the associated {{domxref("BackgroundFetchRegistration")}} object.
+
 ## Syntax
 
 ```js
@@ -32,7 +34,7 @@ One of the following strings:
 
 ## Examples
 
-Logging {{domxref("BackgroundFetchRegistration.result")}} to the console returns a string indicating the status, or an empty string if the fetch is still active.
+Logging this property to the console returns a string indicating the status, or an empty string if the fetch is still active.
 
 ```js
 console.log(bgFetch.result);

diff --git a/files/en-us/web/api/backgroundfetchregistration/uploaded/index.md b/files/en-us/web/api/backgroundfetchregistration/uploaded/index.md
@@ -9,10 +9,12 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.uploaded
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`uploaded`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns the size in bytes successfully sent, initially `0`.
 
+If the value of this property changes, the  [progress](/en-US/docs/Web/API/BackgroundFetchRegistration/progress_event) event is fired at the associated {{domxref("BackgroundFetchRegistration")}} object.
+
 ## Syntax
 
 ```js
@@ -25,7 +27,7 @@ A {{jsxref("number")}}.
 
 ## Examples
 
-Logging {{domxref("BackgroundFetchRegistration.uploaded")}} to the console returns the number of bytes uploaded.
+Logging this property to the console returns the number of bytes uploaded.
 
 ```js
 console.log(bgFetch.uploaded);

diff --git a/files/en-us/web/api/backgroundfetchregistration/uploadtotal/index.md b/files/en-us/web/api/backgroundfetchregistration/uploadtotal/index.md
@@ -9,7 +9,7 @@ tags:
   - BackgroundFetchRegistration
 browser-compat: api.BackgroundFetchRegistration.uploadTotal
 ---
-{{DefaultAPISidebar("Background Fetch API")}}
+{{APIRef("Background Fetch API")}}
 
 The **`uploadTotal`** read-only property of the {{domxref("BackgroundFetchRegistration")}} interface returns the total number of bytes to be sent to the server.