CrossBrowdy API documentation

Namespace: XHR

CB_Net. XHR

Static class to manage XMLHttpRequest (XHR, AJAX) and related. It will return itself if it is tried to be instantiated.

Source:
To Do:
  • Think about providing an easy way to abort XHR (AJAX) calls.

Methods

<static> call(URL [, method] [, data] [, headers] [, responseType] [, mimeType] [, callbackFunction] [, callbackFunctionOK] [, callbackFunctionError] [, allowedSuccessStatuses] [, asynchronous] [, XHR]) → {Object|null}

Performs an AJAX (XHR) call.

Parameters:
Name Type Argument Default Description
URL string

The URL that we want to call. It can also contain URL (GET) parameters.
method string <optional>
 'POST'

The HTTP method that will be used to perform the call (GET, POST, PUT, DELETE, etc.).
data string | Object <optional>

The data that we want to send. If a string is given and "GET" method is being used, it will assume they are GET (URL) parameters and will be attached at the end of the URL given. If something which is not a string is given, it will assume it is a JSON object and will try to convert it into a string (using the JSON.stringify function internally) before sending it.
headers CB_Net.XHR.HEADERS <optional>

Object containing the HTTP header names and their values that we want to send (used internally by the setRequestHeader method of the XHR object).
responseType string <optional>

If provided, it will be used for the responseType property of the XHR object (if available).
mimeType string <optional>

MIME type that will be used to override the default one returned by the server. Only used when the client supports the overrideMimeType method of the XHR object.
callbackFunction function <optional>

Function that will be used for the onreadystatechange property of the XHR object. The unique parameter that it will receive is the XHR object used by the request. If provided, the "callbackFunctionOK" and "callbackFunctionError" parameters will not be used even they were also provided.
callbackFunctionOK function <optional>

Function that will be called by an internally-created function used in the onreadystatechange property of the XHR object when the readyState property is 4 and the status property is included in the "allowedSuccessStatuses" desired. The first parameter it will receive is the XHR object used by the request and the second one will be the "callbackFunctionError" function provided (if any). It will not be used if the parameter "callbackFunction" is provided.
callbackFunctionError function <optional>

Function that will be called by an internally-created function used in the onreadystatechange property of the XHR object when the readyState property is 4 and the status property is not included in the "allowedSuccessStatuses" desired. The first parameter it will receive is the XHR object used by the request and the second one will be the "callbackFunctionOk" function provided (if any). It will not be used if the parameter "callbackFunction" is provided.
allowedSuccessStatuses integer | array <optional>
 200

An integer or a numeric array with a list of integers with the status or statuses that will be considered as a success call by the "callbackFunctionOK" function (only when it is used) when the response comes.
asynchronous boolean <optional>
 true

Defines whether to make a request asynchronously or not. It will be used for the third parameter of the method open of the XHR object.
XHR Object <optional>

The XHR object that we want to use for the call. If not provided, it will try to create a new one internally.
Source:
To Do:
  • Think about providing a way to choose whether we want the "data" provided to be added to the URL when the "GET" method is used or not.
  • Describe better what kind of XHR object will the different callbacks receive, as in some cases (as when using REST) they can contain some special properties with HTTP headers, etc.
Returns:

Returns null if the URL provided was empty or the AJAX (XHR) object provided is not a valid object or it could not be created a new one internally. Otherwise, it returns the AJAX (XHR) object used to try to perform the call (even that maybe it failed or will fail later).

Type
Object | null

<static> callBinary(URL [, data] [, headers] [, blobOrArrayBuffer] [, callbackFunction] [, callbackFunctionOK] [, callbackFunctionError] [, allowedSuccessStatuses] [, XHR]) → {Object|null}

Performs a standard XHR request for a binary file. Uses the CB_Net.XHR.call function internally with "GET" method, using "text/plain; charset=x-user-defined" for the "mimeType" parameter and asynchronously.

Parameters:
Name Type Argument Default Description
URL string

Used for the "URL" parameter of the CB_Net.XHR.call function when it is called internally.
data string | Object <optional>

Used for the "data" parameter of the CB_Net.XHR.call function when it is called internally.
headers CB_Net.XHR.HEADERS <optional>
 { "Content-Type" : "text/plain; charset=x-user-defined", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }

Object containing the HTTP header names and their values that we want to send. If not provided, it will use the default one. An empty object ({}) can be used if we do not want to send any HTTP headers at all. Used for the "headers" parameter of the CB_Net.XHR.call function when it is called internally.
blobOrArrayBuffer 'arraybuffer' | 'blob' | '' <optional>
 'arraybuffer'

Used for the responseType parameter of the CB_Net.XHR.call function when it is called internally. If an empty string is provided, the responseType parameter will not be modified.
callbackFunction function <optional>

Used for the "callbackFunction" parameter of the CB_Net.XHR.call function when it is called internally.
callbackFunctionOK function <optional>

Used for the "callbackFunctionOK" parameter of the CB_Net.XHR.call function when it is called internally.
callbackFunctionError function <optional>

Used for the "callbackFunctionError" parameter of the CB_Net.XHR.call function when it is called internally.
allowedSuccessStatuses integer | array <optional>
 200

Used for the "allowedSuccessStatuses" parameter of the CB_Net.XHR.call function when it is called internally.
XHR Object <optional>

Used for the "XHR" parameter of the CB_Net.XHR.call function when it is called internally.
Source:
Returns:

Returns the same that the CB_Net.XHR.call function returns (called internally).

Type
Object | null

<static> callForm(URL [, data] [, headers] [, responseType] [, charset] [, callbackFunction] [, callbackFunctionOK] [, callbackFunctionError] [, allowedSuccessStatuses] [, XHR]) → {Object|null}

Performs a standard XHR request to send form data by POST (no files). Uses the CB_Net.XHR.call function internally with "POST" method, asynchronously and "mimeType" parameter not provided.

Parameters:
Name Type Argument Default Description
URL string

Used for the "URL" parameter of the CB_Net.XHR.call function when it is called internally.
data string | Object <optional>

Used for the "data" parameter of the CB_Net.XHR.call function when it is called internally.
headers CB_Net.XHR.HEADERS <optional>
 { "Content-Type" : "application/x-www-form-urlencoded; charset=" + charset, "Cache-Control" : "no-cache", "Pragma" : "no-cache" }

Object containing the HTTP header names and their values that we want to send. If not provided, it will use the default one that will include the charset defined by the "charset" parameter. An empty object ({}) can be used if we do not want to send any HTTP headers at all. Used for the "headers" parameter of the CB_Net.XHR.call function when it is called internally.
responseType string <optional>

Used for the responseType parameter of the CB_Net.XHR.call function when it is called internally.
charset string <optional>
 'UTF-8'

The charset for the "Content-Type" HTTP header that will be sent by default only when no "headers" parameter is provided.
callbackFunction function <optional>

Used for the "callbackFunction" parameter of the CB_Net.XHR.call function when it is called internally.
callbackFunctionOK function <optional>

Used for the "callbackFunctionOK" parameter of the CB_Net.XHR.call function when it is called internally.
callbackFunctionError function <optional>

Used for the "callbackFunctionError" parameter of the CB_Net.XHR.call function when it is called internally.
allowedSuccessStatuses integer | array <optional>
 200

Used for the "allowedSuccessStatuses" parameter of the CB_Net.XHR.call function when it is called internally.
XHR Object <optional>

Used for the "XHR" parameter of the CB_Net.XHR.call function when it is called internally.
Source:
Returns:

Returns the same that the CB_Net.XHR.call function returns (called internally).

Type
Object | null

<static> callProxy(URL [, method] [, data] [, headers] [, responseType] [, forceJSON] [, getHeaders] [, headersForceOneDimension] [, headersForceOneDimensionValues] [, transparentStatus] [, transparentHeaders] [, callbackFunction] [, callbackFunctionOK] [, callbackFunctionError] [, allowedSuccessStatuses] [, XHR]) → {Object|null}

Performs an AJAX (XHR) call through the proxy (made with PHP language and using cURL, so it will need a server which supports that) to avoid cross-domain request limitations of AJAX. Uses the CB_Net.XHR.callForm function (with "headers" and "charset" parameters not provided) internally to call the proxy.


NOTE: Edit the "CB_proxy.config.php" file to configure the default proxy (set by default in the value of the CB_Configuration.CrossBase.CB_Net_XHR_PROXY_URL property). Apart from configuring it, adding some security measures is highly recommended.
Have in mind that, for safety reasons, the default proxy only allows to request the URLs defined in the "$allowedURLs" array in the "CB_proxy.config.php" file. Just edit it to allow other URLs.

Parameters:
Name Type Argument Default Description
URL string

The URL that we want the proxy to call for us. It can also contain URL (GET) parameters.
method string <optional>
 'POST'

The HTTP method (GET, POST, PUT, DELETE, etc.) that we want the proxy to use for us when performing the call.
data string | Object <optional>

The data that we want to send through the proxy to the final server. If something which is not a string is given, it will assume it is a JSON object and will try to convert it into a string (using the JSON.stringify function internally) before sending it.
headers CB_Net.XHR.HEADERS <optional>

Object (JSON format) containing the HTTP header names and their values that we want the proxy to send to the final server. Even if not provided, the proxy could end sending some HTTP headers depending on the cURL configuration used.
responseType string <optional>

Used for the responseType parameter of the CB_Net.XHR.callForm function when it is called internally.
forceJSON boolean <optional>
 false

If it is set to true, the response from the proxy will be a JSON object with the status property containing the HTTP status of the reply, the response property with the response content itself and the "headers" property (only when "getHeaders" parameters is set to true) with the HTTP headers of the reply, all belonging to the response from the final server.
getHeaders boolean <optional>
 false

If it is set to true, the proxy will answer including the HTTP headers from the final server. The HTTP headers will be included in the final response string at the beginning (before the response content) if the "forceJSON" parameter is not set to true or in the "headers" property of the JSON object that belongs to the response otherwise.
headersForceOneDimension boolean <optional>
 false

If it is set to true, the proxy will consider that the HTTP headers of the response from the final server are not multidimensional which means that the final server would never reply the same HTTP header repeated multiple times (with different values, normally) in different chunks separated by double new lines ("\r\n\r\n"). Default value (false) is recommended. Needs "getHeaders" set to true.
headersForceOneDimensionValues boolean <optional>
 false

If it is set to true, the proxy will only consider one value per HTTP header from the response from the final server. Default value (false) is recommended. Needs "getHeaders" set to true.
transparentStatus boolean <optional>
 false

If it is set to true, the proxy will reply us with the same status as the final server in its HTTP response.
transparentHeaders boolean <optional>
 false

If it is set to true, the proxy will reply us with the same HTTP headers as the final server in its HTTP response.
callbackFunction function <optional>

Used for the "callbackFunction" parameter of the CB_Net.XHR.callForm function when it is called internally.
callbackFunctionOK function <optional>

Used for the "callbackFunctionOK" parameter of the CB_Net.XHR.callForm function when it is called internally.
callbackFunctionError function <optional>

Used for the "callbackFunctionError" parameter of the CB_Net.XHR.callForm function when it is called internally.
allowedSuccessStatuses integer | array <optional>
 200

Used for the "allowedSuccessStatuses" parameter of the CB_Net.XHR.callForm function when it is called internally.
XHR Object <optional>

Used for the "XHR" parameter of the CB_Net.XHR.callForm function when it is called internally.
Source:
To Do:
  • Document PHP proxy more.
Returns:

Returns the same that the CB_Net.XHR.callForm function returns (called internally).

Type
Object | null

<static> callREST( [serverURL] [, route] [, dataURL] [, method] [, data] [, headers] [, responseType] [, avoidProxy] [, forceJSON] [, getHeaders] [, headersForceOneDimension] [, headersForceOneDimensionValues] [, transparentStatus] [, transparentHeaders] [, callbackFunctionOK] [, callbackFunctionError] [, allowedSuccessStatuses] [, XHR]) → {Object|null}

Performs a REST call to a REST server. Uses the CB_Net.XHR.callProxy function (without "callbackFunction" parameter provided) internally if we do not want to avoid the proxy or uses the CB_Net.XHR.call function (asynchronously, with "mimeType" and "callbackFunction" parameters not provided) otherwise.

Parameters:
Name Type Argument Default Description
serverURL string <optional>
 CB_Net.REST.SERVER_URL_DEFAULT

The URL of the REST server that we want to call. It should not contain URL (GET) parameters. It can also contain the REST path (route), although it is recommended to set it in the "route" parameter.
route string <optional>

The REST path (route) we want to request. It can also contain URL (GET) parameters, although it is recommended to set them in the "dataURL" parameter.
dataURL string <optional>

The URL (GET) data that we want to send.
method string <optional>
 'POST'

Used for the "method" parameter for the CB_Net.XHR.callProxy function or for the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
data string | Object <optional>

Used for the "data" parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
headers CB_Net.XHR.HEADERS <optional>
 undefined|{ "Content-Type" : "application/x-www-form-urlencoded; charset=UTF-8", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }

Used for the "headers" parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally. If not provided and the CB_Net.XHR.call function is used (if no proxy is allowed), the default value will be: { "Content-Type" : "application/x-www-form-urlencoded; charset=UTF-8", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }
responseType string <optional>

Used for the responseType parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
avoidProxy boolean <optional>
 false

If it is set to true, it will call the CB_Net.XHR.call internally. Otherwise, it will use the CB_Net.XHR.callProxy function internally.
forceJSON boolean <optional>
 false

Used for the "forceJSON" parameter of the CB_Net.XHR.callProxy function (if the proxy is allowed) when it is called internally.
getHeaders boolean <optional>
 false

Used for the "getHeaders" parameter of the CB_Net.XHR.callProxy function (if the proxy is allowed) when it is called internally.
headersForceOneDimension boolean <optional>
 false

Used for the "headersForceOneDimension" parameter of the CB_Net.XHR.callProxy function (if the proxy is allowed) when it is called internally.
headersForceOneDimensionValues boolean <optional>
 false

Used for the "headersForceOneDimensionValues" parameter of the CB_Net.XHR.callProxy function (if the proxy is allowed) when it is called internally.
transparentStatus boolean <optional>
 false

Used for the "transparentStatus" parameter of the CB_Net.XHR.callProxy function (if the proxy is allowed) when it is called internally.
transparentHeaders boolean <optional>
 false

Used for the "transparentHeaders" parameter of the CB_Net.XHR.callProxy function (if the proxy is allowed) when it is called internally.
callbackFunctionOK function <optional>

Used for the "callbackFunctionOK" parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
callbackFunctionError function <optional>

Used for the "callbackFunctionError" parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
allowedSuccessStatuses integer | array <optional>
 200

Used for the "allowedSuccessStatuses" parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
XHR Object <optional>

Used for the "XHR" parameter of the CB_Net.XHR.callProxy function or of the CB_Net.XHR.call function (if no proxy is allowed) when it is called internally.
Source:
Returns:

When using the proxy is allowed, returns the same that the CB_Net.XHR.callProxy function returns (called internally). Otherwise, it returns the same that the CB_Net.XHR.call function returns (called internally).

Type
Object | null

<static> get() → {Object|null}

Returns a new AJAX (XHR) object, if possible.

Source:
Returns:

Returns a new AJAX (XHR) object if it has been possible to create it or null otherwise.

Type
Object | null

<static> getResponseContent(response [, sanitize]) → {string|null}

Returns the response content from an XHR object (from its responseText property) or from the JSON response generated by the "getSslPage" function used by the PHP proxy (response property). Useful to parse the response from the CB_Net.XHR.callProxy (or CB_Net.XHR.callREST and related) function when it has been called with the "forceJSON" parameter set to true.

Parameters:
Name Type Argument Default Description
response Object | string

The XHR object which contains the responseText property or the value of the responseText property (string) itself which should contain the JSON response generated by the "getSslPage" function used by the PHP proxy. If a string is provided, tries to parse it as a JSON object. The responseText property (or the response property as a fallback) will be tried to be returned from it.
sanitize boolean <optional>
 true

If it is set to true and neither the responseText nor the response properties are found, it will return an empty string ("") instead of returning null.
Source:
Returns:

Returns the content of the responseText (or response) property if possible. If it is not possible, it will return null if the parameter "sanitize" is set to false or an empty string ("") otherwise.

Type
string | null

<static> getResponseHeaders(response [, sanitize]) → {Object|null}

Returns the HTTP headers (it should be an object) from the JSON response generated by the "getSslPage" function used by the PHP proxy ("headers" property). Useful to parse the response from the CB_Net.XHR.callProxy (or CB_Net.XHR.callREST and related) function when it has been called with the "forceJSON" parameter set to true.

Parameters:
Name Type Argument Default Description
response Object | string

The XHR object which contains the responseText property or the value of the responseText property (string) itself which should contain the JSON response generated by the "getSslPage" function used by the PHP proxy. If a string is provided, tries to parse it as a JSON object. The "headers" property will be tried to be returned from it.
sanitize boolean <optional>
 true

If it is set to true and the "headers" property is not found, it will return an empty object ({}) instead of returning null.
Source:
To Do:
  • Consider adding the parameter "headerNameFirst".
Returns:

Returns the content of the "headers" property if possible (it should be a CB_Net.XHR.HEADERS object). If it is not possible, it will return null if the parameter "sanitize" is set to false or an empty object ({}) otherwise.

Type
Object | null

<static> getStatusCode(response [, sanitize] [, statusDefault]) → {integer|*}

Returns the HTTP status code from an XHR object (status property) or from the info array generated by the PHP's curl_getinfo function ("http_code" index) or from the JSON response generated by the "getSslPage" function used by the PHP proxy (status property). Useful to parse the response from the CB_Net.XHR.callProxy (or CB_Net.XHR.callREST and related) function when it has been called with the "forceJSON" parameter set to true.

Parameters:
Name Type Argument Default Description
response Object | string

The XHR object which contains the status property or the value of the responseText property (string) itself which should contain the JSON response generated by the "getSslPage" function used by the PHP proxy. If a string is provided, tries to parse it as a JSON object. The status property will be tried to be returned from it (or the "http_code" property as a fallback).
sanitize boolean <optional>
 true

If it is set to true and neither the "status" nor the "http_code" property are found (or is not a number), it will return the value of "statusDefault" instead of returning null.
statusDefault boolean <optional>
 -1

Default value to return when the status cannot be found (or is not a number). Only used when the "sanitize" parameter is set to true.
Source:
Returns:

Returns the content of the status (or "http_code") property if possible (it should be an integer). If it is not possible, it will return null if the parameter "sanitize" is set to false or the value of "statusDefault" otherwise.

Type
integer | *

<static> supported() → {boolean}

Returns whether AJAX (XHR) is available or not.

Source:
Returns:

Returns true if XHR (AJAX) objects can be used.

Type
boolean

Type Definitions

HEADERS

Object containing the HTTP headers and their values.

Type:
  • Object
Properties:
Name Type Description
HTTPHeaderName Object

Each property name is an HTTP header and its value is the desired one for this header.
Source:
Example
{ "Content-Type" : "text/plain; charset=x-user-defined", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }