fetch: Difference between revisions

From RPTools Wiki
Jump to navigation Jump to search
VisualWikitext
m (Fixed top-level macro formatting; reformatted JS example)
m (Fixed some typos; added comments to example; added reference to 'macro.requestHeaders' var)
 
(2 intermediate revisions by the same user not shown)
Line 3: Line 3:
|name=fetch
|name=fetch
|version=1.11.4
|version=1.11.4
|description=Fetches a URI via javascript.  Wrapper around {{func|XMLHttpRequest}}.
|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>


'''Parameter'''
'''Parameters'''
{{param|target|The macro to call or asset to retrieve.  <code>lib://<libraryName>/macro/<macroName></code> style lib-URIs work, as do <code>asset://<asset-hash></code> (as returned by the {{func|getImage}} function).  macros use a locationless-URI <code>macro:macroName@macroLocation</code> }}
{{param|target|The macro to call or asset to retrieve.  {{code|lib://<libraryName>/macro/<macroName>}} style lib-URIs work, as do {{code|asset://<asset-hash>}} (as returned by the {{func|getImage}} function).  Macros use a locationless-URI {{code|macro:macroName@macroLocation}}.}}
{{param|options|A javascript <code>object</code> mapping optional arguments to values.  Notable options are below}}
{{param|options|A JavaScript {{code|object}} mapping optional arguments to values.  Notable options are discussed at {{func|XMLHttpRequest}}.}}
{{param|method|HTTP Method to emulate.  GET for assets/library resources, POST for macro calls.}}
{{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 ojbect 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</code> API in javascript, you can also create a <code>new Request()</code> 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 promise which resolves when the {{func|XMLHttpRequest}} finishes.   
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.
 
<h3>See Also</h3>


|also=
[[XMLHttpRequest|XMLHttpRequest]]<br/>
[[XMLHttpRequest|XMLHttpRequest]]<br/>
[https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API at MDN]<br/>
[https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API at MDN]
 
[[Category:HTML5 JavaScript]]
 
[[Category:HTML5 javascript]]
}}
}}

Latest revision as of 23:59, 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 do asset://<asset-hash> (as returned by the getImage() function). Macros use a locationless-URI macro:macroName@macroLocation.
  • options - A JavaScript object mapping optional arguments to values. Notable options are discussed at XMLHttpRequest().
  • method - HTTP Method to emulate. Use GET for assets/library resources, POST for macro calls that you want to send parameters to. (Using GET for 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 a Promise which 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.


See Also

XMLHttpRequest
Fetch API at MDN
Retrieved from "https://wiki.rptools.info/index.php?title=fetch&oldid=34929"