XMLHttpRequest: Difference between revisions
Jump to navigation
Jump to search
m (Clean up formatting) |
m (Cleaned up formatting) |
||
| Line 3: | Line 3: | ||
|name=XMLHttpRequest | |name=XMLHttpRequest | ||
|version=1.11.4 | |version=1.11.4 | ||
|description=Runs a macro or fetches an asset or library resource via standard XMLHttpRequest API. | |description=Runs a macro or fetches an asset or library resource via standard {{code|XMLHttpRequest}} API. | ||
|usage= | |usage= | ||
<syntaxhighlight lang="javascript" line> | <syntaxhighlight lang="javascript" line> | ||
let x = new XMLHttpRequest(); | let x = new XMLHttpRequest(); | ||
x.open(method, target, nonblocking, user, password) | x.open(method, target, nonblocking, user, password); | ||
</syntaxhighlight> | </syntaxhighlight> | ||
''' | '''Parameters''' | ||
{{param|method|HTTP Method to emulate. GET for assets/library resources, POST for macro calls.}} | {{param|method|HTTP Method to emulate. {{code|GET}} for assets/library resources, {{code|POST}} for macro calls.}} | ||
{{param|target|The macro to call or asset to retrieve. | {{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|nonblocking| | {{param|nonblocking|True if the {{code|XMLHttpRequest}} should not block the JavaScript frame. Default is {{code|true}}. Blocking {{code|XMLHttpRequest}}s should generally not be used.}} | ||
{{param|user|Username, as a string. For compatibility with the XMLHttpRequest API, but unused.}} | {{param|user|Username, as a string. For compatibility with the {{code|XMLHttpRequest}} API, but unused.}} | ||
{{param|password|Password, as a string. For compatibility with the XMLHttpRequest API, but unused.}} | {{param|password|Password, as a string. For compatibility with the {{code|XMLHttpRequest}} API, but unused.}} | ||
Note you cannot use | Note you cannot use {{code|XMLHTTPRequest}}s to fetch external resources. HTTP/HTTPS is not supported. Aside from the custom target URIs, {{code|XMLHttpRequest}}s should work like native ones living in a browser. You can set response types, pass custom headers, and so on. | ||
If calling a macro, the special variable | If calling a macro, the special variable [[macro.args]] within the macro contains the body of the request. The special variable [[macro.return]] is ignored in the response (it may be used to set an HTTP Response Code at a future date). All output of the macro ({{code|[r: ]}} blocks and the like) are gathered into the response body. | ||
Request headers are available in the macro via the special variable | Request headers are available in the macro via the special variable [[macro.requestHeaders]], which is a JSON object mapping the headers (as strings) to their values (as strings). | ||
Likewise, response headers generated by the macro should be stored into | Likewise, response headers generated by the macro should be stored into [[macro.responseHeaders]] where they will be accessible in JavaScript. The magic header {{code|:Status}} can be used to set the HTTP response code of the request. It is removed from the response headers before they are attached to the {{func|XMLHttpRequest}} object. | ||
|also= | |also= | ||
{{func|fetch}}<br> | {{func|fetch}}<br> | ||
[[macro.args]]<br> | |||
[[macro.return]]<br> | |||
[[macro.requestHeaders]]<br> | |||
[[macro.responseHeaders]]<br> | |||
[https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest XMLHttpRequest API at MDN] | [https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest XMLHttpRequest API at MDN] | ||
[[Category:HTML5 JavaScript]] | [[Category:HTML5 JavaScript]] | ||
}} | }} | ||
Revision as of 21:49, 27 January 2024
This article describes a feature or macro function that is experimental and may be subject to change.
XMLHttpRequest() Function
• Introduced in version 1.11.4
Runs a macro or fetches an asset or library resource via standard
XMLHttpRequest API.Usage
let x = new XMLHttpRequest();
x.open(method, target, nonblocking, user, password);
Parameters
method- HTTP Method to emulate.GETfor assets/library resources,POSTfor macro calls.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.nonblocking- True if theXMLHttpRequestshould not block the JavaScript frame. Default istrue. BlockingXMLHttpRequests should generally not be used.user- Username, as a string. For compatibility with theXMLHttpRequestAPI, but unused.password- Password, as a string. For compatibility with theXMLHttpRequestAPI, but unused.
Note you cannot use XMLHTTPRequests to fetch external resources. HTTP/HTTPS is not supported. Aside from the custom target URIs, XMLHttpRequests should work like native ones living in a browser. You can set response types, pass custom headers, and so on.
If calling a macro, the special variable macro.args within the macro contains the body of the request. The special variable macro.return is ignored in the response (it may be used to set an HTTP Response Code at a future date). All output of the macro ([r: ] blocks and the like) are gathered into the response body.
Request headers are available in the macro via the special variable macro.requestHeaders, which is a JSON object mapping the headers (as strings) to their values (as strings).
Likewise, response headers generated by the macro should be stored into macro.responseHeaders where they will be accessible in JavaScript. The magic header :Status can be used to set the HTTP response code of the request. It is removed from the response headers before they are attached to the XMLHttpRequest() object.