XMLHttpRequest

 This article describes a feature or macro function that is experimental and may be subject to change.

{{MacroFunction |name=XMLHttpRequest |version=1.11.4 |description=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)

Parameter

• method - HTTP Method to emulate. GET for assets/library resources, POST for macro calls.
• 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
• nonblocking - If the XMLHttpRequest should not block the javascript frame, default is true. Blocking XMLHttpRequests should generally not be used.
• user - Username, as a string. There for compatibility with XMLHttpRequest API, but unused.
• password - Password, as a string. There for compatibility with XMLHttpRequest API, but unused.

Note you cannot use XMLHTTPRequests to fetch external resources. HTTP(S) 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 contains the body of the request. The special variable macro.return is ignored (it may be used to set an HTTP Response Code later), and all output of the macro ([r: blocks and the like) are gathered into the response body.

Request headers are available via the special variable macro.requestHeaders, which is a JSON object mapping headers (as strings) to their values (as strings). Likewise, the response headers are available via macro.responseHeaders 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.