XMLHttpRequest

 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)

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. For compatibility with the XMLHttpRequest API, but unused.
• password - Password, as a string. For compatibility with the 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 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.

See Also

fetch()
XMLHttpRequest API at MDN