fetch: Difference between revisions
Jump to navigation
Jump to search
m (Clean up typing, adjust case) |
m (Fixed some typos; added comments to example; added reference to 'macro.requestHeaders' var) |
||
| Line 3: | Line 3: | ||
|name=fetch | |name=fetch | ||
|version=1.11.4 | |version=1.11.4 | ||
|description=Fetches a URI via JavaScript. | |description=Fetches a URI via JavaScript. Compatibility wrapper around {{func|XMLHttpRequest}}. | ||
|usage= | |usage= | ||
| Line 9: | Line 9: | ||
let x = fetch(target, [options]); | let x = fetch(target, [options]); | ||
x.then((response) => { | x.then((response) => { | ||
// JS code here for success return (any 2XX code) | |||
}, (failure) => { | }, (failure) => { | ||
// JS code here for failure status (any non-2XX code) | |||
}); | }); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| Line 17: | Line 19: | ||
{{param|options|A JavaScript {{code|object}} mapping optional arguments to values. Notable options are discussed at {{func|XMLHttpRequest}}.}} | {{param|options|A JavaScript {{code|object}} mapping optional arguments to values. Notable options are discussed at {{func|XMLHttpRequest}}.}} | ||
{{param|method|HTTP Method to emulate. Use {{code|GET}} for assets/library resources, {{code|POST}} for macro calls that you want to send parameters to. (Using {{code|GET}} for macros is possible, but no parameters can be passed as there is no "query string".)}} | {{param|method|HTTP Method to emulate. Use {{code|GET}} for assets/library resources, {{code|POST}} for macro calls that you want to send parameters to. (Using {{code|GET}} for macros is possible, but no parameters can be passed as there is no "query string".)}} | ||
{{param|body|The body of the request to send. Can be a Promise which returns a body. Lazily coerced to string.}} | {{param|body|The body of the request to send. Can be a {{code|Promise}} which returns a body. Lazily coerced to string.}} | ||
{{param|headers|A JavaScript object containing request headers to include}} | {{param|headers|A JavaScript object containing request headers to include. Received in an MTscript macro via [[macro.requestHeaders]].}} | ||
Like the native {{code|fetch}} API in JavaScript, you can also create a {{code|new Request()}} object and pass that in to {{func|fetch}}. Internally, the {{func|fetch}} wrapper does this for you. It then calls {{func|XMLHttpRequest}} and returns | Like the native {{code|fetch}} API in JavaScript, you can also create a {{code|new Request()}} object and pass that in to {{func|fetch}}. Internally, the {{func|fetch}} wrapper does this for you. It then calls {{func|XMLHttpRequest}} and returns a {{code|Promise}} which resolves when the {{func|XMLHttpRequest}} finishes. | ||
See {{func|XMLHttpRequest}} for handling macro headers and macro special variables. | See {{func|XMLHttpRequest}} for handling macro headers and other macro special variables. | ||
|also= | |also= | ||
[[XMLHttpRequest|XMLHttpRequest]] | [[XMLHttpRequest|XMLHttpRequest]]<br/> | ||
[https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API at MDN] | [https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API at MDN] | ||
[[Category:HTML5 JavaScript]] | [[Category:HTML5 JavaScript]] | ||
}} | }} | ||
Revision as of 22:01, 27 January 2024
This article describes a feature or macro function that is experimental and may be subject to change.
fetch() Function
• Introduced in version 1.11.4
Fetches a URI via JavaScript. Compatibility wrapper around XMLHttpRequest().
Usage
let x = fetch(target, [options]);
x.then((response) => {
// JS code here for success return (any 2XX code)
}, (failure) => {
// JS code here for failure status (any non-2XX code)
});
Parameters
target- The macro to call or asset to retrieve.lib://<libraryName>/macro/<macroName>style lib-URIs work, as doasset://<asset-hash>(as returned by the getImage() function). Macros use a locationless-URImacro:macroName@macroLocation.options- A JavaScriptobjectmapping optional arguments to values. Notable options are discussed at XMLHttpRequest().method- HTTP Method to emulate. UseGETfor assets/library resources,POSTfor macro calls that you want to send parameters to. (UsingGETfor macros is possible, but no parameters can be passed as there is no "query string".)body- The body of the request to send. Can be aPromisewhich returns a body. Lazily coerced to string.headers- A JavaScript object containing request headers to include. Received in an MTscript macro via macro.requestHeaders.
Like the native fetch API in JavaScript, you can also create a new Request() object and pass that in to fetch(). Internally, the fetch() wrapper does this for you. It then calls XMLHttpRequest() and returns a Promise which resolves when the XMLHttpRequest() finishes.
See XMLHttpRequest() for handling macro headers and other macro special variables.