recursal/MDN huggingface dataset:
FileSystemFileEntry: createWriter() method
==========================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

 The `FileSystemFileEntry` interface's method
 **`createWriter()`** returns a `FileWriter` object
 which can be used to write data into the file represented by the directory entry.

Syntax
------


```js
createWriter(successCallback)
createWriter(successCallback, errorCallback)
```

### Parameters

`successCallback`

 A callback function which is called when the `FileWriter` has been
 created successfully; the `FileWriter` is passed into the callback as the
 only parameter.


`errorCallback` Optional

 If provided, this must be a method which is called when an error occurs while trying
 to create the `FileWriter`. This callback receives as input a
 `FileError` object describing the error.


### Return value

None (`undefined`).

Examples
--------

 This example establishes a method, `writeToFileEntry()`, which outputs a
 text string to the file corresponding to the passed-in directory entry.


```js
function writeToFileEntry(entry, text) {
  entry.createWriter(
    (fileWriter) => {
      let data = Blob([text], { type: "text/plain" });

      fileWriter.write(data);
    },
    (fileError) => {
      /\* do whatever to handle the error \*/
    },
  );
}
```


 The success callback for the `createWriter()` call takes the text which was
 passed in and creates a new `Blob` object of type `text/plain`
 that contains the passed text. This blob is then output to the `FileWriter`
 object to be written to the file.

Specifications
--------------

This feature is not part of any specification anymore. It is no longer on track to become a standard.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* File and Directory Entries API
* Introduction to the File and Directory Entries API
FileSystemFileEntry: file() method
==================================

 The `FileSystemFileEntry` interface's method
 **`file()`** returns a
 `File` object which can be used to read data from the file represented by
 the directory entry.

Syntax
------


```js
file(successCallback)
file(successCallback, errorCallback)
```

### Parameters

`successCallback`

 A callback function which is called when the `File` has been created
 successfully; the `File` is passed into the callback as the only parameter.


`errorCallback` Optional

 If provided, this must be a method which is called when an error occurs while trying
 to create the `File`. This callback receives as input a
 `DOMException` object describing the error.


### Return value

None (`undefined`).

Examples
--------

 This example establishes a method, `readFile()`, reads a text file and calls
 a specified callback function with the received text (in a string)
 once the read is completed. If an error occurs, a specified (optional) error callback is
 called.


```js
function readFile(entry, successCallback, errorCallback) {
  entry.file((file) => {
    let reader = new FileReader();

    reader.onload = () => {
      successCallback(reader.result);
    };

    reader.onerror = () => {
      errorCallback(reader.error);
    };

    reader.readAsText(file);
  }, errorCallback);
}
```


 This function calls `file()`, specifying as its success callback a method
 which proceeds to use a `FileReader` to read the file as text. The
 FileReader's `load` event handler is set up to deliver the loaded string to
 the `successCallback` specified when the `readFile()` method was
 called; similarly, its `error` handler is set up to call the
 `errorCallback` specified.

Specifications
--------------

| Specification |
| --- |
| File and Directory Entries API # dom-filesystemfileentry-file |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* File and Directory Entries API
* Introduction to the File and Directory Entries API
MerchantValidationEvent: complete() method
==========================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The `MerchantValidationEvent` method **`complete()`** takes merchant-specific information previously received from the `validationURL` and uses it to validate the merchant.

All you have to do is call `complete()` from your handler for the `merchantvalidation` event, passing in the data fetched from the `validationURL`.

Syntax
------


```js
complete(validationData)
complete(merchantSessionPromise)
```

### Parameters

`validationData` or `merchantSessionPromise`

An object containing the data needed to complete the merchant validation process, or a `Promise` which resolves to the validation data.

### Return value

None (`undefined`).

### Exceptions

This exception may be passed into the rejection handler for the promise:

`InvalidStateError` `DOMException`

Returned if the event did not come directly from the user agent, but was instead dispatched by other code. Another payment request is currently being processed, the current payment request is not currently being displayed to the user, or payment information is currently being updated.

Examples
--------

In this example, we see the client-side code needed to support merchant validation for a payment request called `payRequest`:


```js
payRequest.onmerchantvalidation = (event) => {
  const validationDataPromise = getValidationData(event.validationURL);
  event.complete(validationDataPromise);
};

function getValidationData(url) {
  // Retrieve the validation data from the URL
  // …
}
```


This code sets up a handler for the `merchantvalidation` event. The event handler calls a function, `getValidationData()`, which retrieves the data from the validation URL, then passes that data (or a promise to deliver the data) into `complete()`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Payment Request API
* Using the Payment Request API
* Payment processing concepts
MerchantValidationEvent: methodName property
============================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The `MerchantValidationEvent` property
 **`methodName`** is a read-only value which returns a string
 indicating the payment method identifier which represents the payment handler that
 requires merchant validation.

Value
-----

 A read-only string which uniquely identifies the payment handler
 which is requesting merchant validation. See
 Merchant validation for more information on the process.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Payment Request API
* Using the Payment Request API
* Payment processing concepts
MerchantValidationEvent: validationURL property
===============================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

 The `MerchantValidationEvent` property
 **`validationURL`** is a read-only string value providing the
 URL from which to fetch the payment handler-specific data needed to validate the
 merchant.

This data should be passed into the `complete()` method to let the user agent complete the transaction.

Value
-----

 A read-only string giving the URL from which to load payment handler
 specific data needed to complete the merchant verification process. Once this has been
 loaded, it should be passed into `complete()`, either directly or using a promise.

See Merchant validation to learn more about the process.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Payment Request API
* Using the Payment Request API
* Payment processing concepts
MerchantValidationEvent: MerchantValidationEvent() constructor
==============================================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`MerchantValidationEvent()`** constructor creates a new `MerchantValidationEvent` object. You should not have to create these events yourself; instead, just handle the `merchantvalidation` event.

Syntax
------


```js
new MerchantValidationEvent(type)
new MerchantValidationEvent(type, options)
```

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers always set it to `merchantvalidation`.


`options` Optional

An object that, *in addition of the properties defined in `Event()`*, can have the following properties:

`methodName` Optional

A string containing the payment method identifier for the payment handler being used. This is an empty string by default.

`validationURL` Optional

The URL from which to retrieve payment handler specific verification information used to validate the merchant. This is an empty string by default.


### Return value

 A new `MerchantValidationEvent` object providing the information
 that needs to be delivered to the client-side code to present to the user agent by calling `complete()`.

### Exceptions

`TypeError`

Thrown if the string specified as `validationURL` could not be parsed as a URL.

`RangeError`

Thrown if the specified `methodName` does not correspond to a known and supported merchant or is not a well-formed standard payment method identifier.

Specifications
--------------

*This feature is deprecated and is not part of any specification.*

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Payment Request API
* Using the Payment Request API
* Payment processing concepts
NavigationHistoryEntry: key property
====================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`key`** read-only property of the `NavigationHistoryEntry` interface returns the `key` of the history entry, or an empty string if current document is not fully active. This is a unique, UA-generated value that represents the history entry's slot in the entries list. It is used to navigate that particular slot via `Navigation.traverseTo()`. The `key` will be reused by other entries that replace the entry in the list (that is, if the `NavigateEvent.navigationType` is `replace`).

This differs from the `id` of a history entry. The `id` is a unique, UA-generated value that always represents a specific history entry rather than its slot in the entries list. This is useful to correlate it with an external resource such as a storage cache.

Value
-----

A string representing the `key` of the `NavigationHistoryEntry`.

Examples
--------

### Basic usage


```js
const current = navigation.currentEntry;
console.log(current.key);
```

### Set up a home button


```js
function initHomeBtn() {
  // Get the key of the first loaded entry
  // so the user can always go back to this view.
  const { key } = navigation.currentEntry;
  backToHomeButton.onclick = () => {
    navigation.traverseTo(key);
  };
}
// Intercept navigate events, such as link clicks, and
// replace them with single-page navigations
navigation.addEventListener("navigate", (event) => {
  event.intercept({
    async handler() {
      // Navigate to a different view,
      // but the "home" button will always work.
    },
  });
});
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-navigationhistoryentry-key-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
NavigationHistoryEntry: url property
====================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`url`** read-only property of the `NavigationHistoryEntry` interface returns the absolute URL of this history entry. If the entry corresponds to a different Document than the current one (like `sameDocument` property is `false`), and that Document was fetched with a `referrer policy` header set to `no-referrer` or `origin`, the property returns `null`. If current document is not fully active, it returns an empty string.

Value
-----

A string representing the URL or `null`.

Examples
--------


```js
const current = navigation.currentEntry;
console.log(current.url);
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-navigationhistoryentry-url-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
NavigationHistoryEntry: id property
===================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`id`** read-only property of the `NavigationHistoryEntry` interface returns the `id` of the history entry, or an empty string if current document is not fully active. This is a unique, UA-generated value that always represents a specific history entry, useful to correlate it with an external resource such as a storage cache.

This differs from the `key` of a history entry. The `key` is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. It is used to navigate that particular slot via `Navigation.traverseTo()`. The `key` will be reused by other entries that replace the entry in the list (that is, if the `NavigateEvent.navigationType` is `replace`).

Value
-----

A string representing the `id` of the `NavigationHistoryEntry`.

Examples
--------


```js
const current = navigation.currentEntry;
console.log(current.id);
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-navigationhistoryentry-id-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
NavigationHistoryEntry: dispose event
=====================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`dispose`** event of the `NavigationHistoryEntry` interface is fired when the entry is no longer part of the history entry list.

Disposal occurs when:

* Forward history entries are cleared. See the example at Notifications on entry disposal for more information.
* The user clears their browser history using settings or provided UI controls.
* The history limit is exceeded. This is not specified anywhere, but browsers tend to have a history limit of 50 pages.
Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("dispose", (event) => {});

ondispose = (event) => {};
```

Event type
----------

A generic `Event`.

Examples
--------


```js
navigation.addEventListener("currententrychange", () => {
  navigation.currentEntry.addEventListener("dispose", disposeHandler);
});
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # handler-navigationhistoryentry-ondispose |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
NavigationHistoryEntry: sameDocument property
=============================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`sameDocument`** read-only property of the `NavigationHistoryEntry` interface returns `true` if this history entry is for the same `document` as the current `Document` value and current document is fully active, or `false` otherwise.

Value
-----

A boolean.

Examples
--------


```js
const current = navigation.currentEntry;
console.log(current.sameDocument);
// Will always return true
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-navigationhistoryentry-samedocument-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
NavigationHistoryEntry: getState() method
=========================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`getState()`** method of the `NavigationHistoryEntry` interface returns a clone of the developer-supplied state associated with this history entry.

Syntax
------


```js
getState()
```

### Parameters

None.

### Return value

A value representing the state. This can be any structured-cloneable data type.

If no state is defined or if current document is not fully active, it returns `undefined`.

### Exceptions

None.

Examples
--------


```js
async function handleReload() {
  // Update existing state via reload()
  await navigation.reload({
    state: { ...navigation.currentEntry.getState(), newState: 3 },
  });

  // Print current state to the console
  const current = navigation.currentEntry;
  console.log(current.getState());
}
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-navigationhistoryentry-getstate-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
* Methods that allow state to be updated — `Navigation.navigate()`, `Navigation.reload()`, and `Navigation.updateCurrentEntry()`
NavigationHistoryEntry: index property
======================================

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`index`** read-only property of the `NavigationHistoryEntry` interface returns the index of the history entry in the history entries list (that is, the list returned by `Navigation.entries()`), or `-1` if the entry does not appear in the list or if current document is not fully active.

Value
-----

A number representing the `index` of the entry in the history entries list, or `-1` if this item does not appear in the list.

Examples
--------


```js
const current = navigation.currentEntry;
console.log(current.index);
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-navigationhistoryentry-index-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Modern client-side routing: the Navigation API
* Navigation API explainer
* Domenic Denicola's Navigation API live demo
PageTransitionEvent: persisted property
=======================================

The **`persisted`** read-only property indicates if a webpage is loading from a cache.

Value
-----

A boolean value.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-pagetransitionevent-persisted-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
PageTransitionEvent: PageTransitionEvent() constructor
======================================================

The **`PageTransitionEvent()`** constructor creates a new `PageTransitionEvent` object, that is used by the `pageshow` or `pagehide` events, fired at the `window` object when a page is loaded or unloaded.

**Note:** A web developer doesn't typically need to call this constructor, as the browser creates these objects itself when firing `pageshow` or `pagehide` events.

Syntax
------


```js
new PageTransitionEvent(type, options)
```

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `pageshow` or `pagehide`.


`options` Optional

An object that, *in addition to the properties defined in `Event()`*, has the following property:

`persisted` Optional

A boolean indicating if the document is loading from a cache.


### Return value

A new `PageTransitionEvent` object.

Specifications
--------------

| Specification |
| --- |
| HTML Standard # the-pagetransitionevent-interface |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `pageshow` event
* `pagehide` event