# 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:
  - CrossBase/net/XHR/CB_Net_XHR.js, line 15
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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 120
  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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 341

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 293

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 403
  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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 469

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 60

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 581

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 546
  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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 563

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 40

  ##### 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:
    - CrossBase/net/XHR/CB_Net_XHR.js, line 92

  ##### Example

      { "Content-Type" : "text/plain; charset=x-user-defined", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }

#### Search results