CrossBrowdy - Basic tutorial

Networking

XHR (AJAX) and XDR (Cross-domain requests)

Here is an example of using XHR (AJAX):


	//Checks whether XHR (AJAX) is supported:
	if (CB_Net.XHR.supported())
	{
		CB_console("XHR (AJAX) is supported.");
		
		//Defines the function called when the request succeeds (the status is in the "allowedSuccessStatuses" provided, which is 200 by default):
		var successFunction = function(XHR, callbackFunctionError)
		{
			CB_console("AJAX call succeeded! Status code is: " + CB_Net.XHR.getStatusCode(XHR));
			CB_console("Content: " + CB_Net.XHR.getResponseContent(XHR));
		};
		
		//Defines the function called when the request does not succeed (the status is not in the "allowedSuccessStatuses" provided, which is 200 by default):
		var errorFunction = function(XHR, callbackFunctionOK)
		{
			CB_console("AJAX call failed! Status code is: " + CB_Net.XHR.getStatusCode(XHR));
			CB_console("Content: " + CB_Net.XHR.getResponseContent(XHR));
		};
		
		//Performs an AJAX call:
		var XHR = CB_Net.XHR.call
		(
			//Parameters ("null" or "undefined" ones will get their default value, if needed, automatically):
			"path_to/whatever.txt", //URL. Unique mandatory parameter.
			"GET", //method. Default: 'POST'.
			"parameter1=value1&parameter2=value2", //data. It can be either a string (like URL parameters) or a JSON object. Default: undefined.
			{ "Content-Type" : "text/plain; charset=x-user-defined", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }, //headers. Default: undefined.
			null, //responseType. Default: undefined.
			null, //mimeType. Default: undefined.
			null, //callbackFunction. Default: undefined. If provided, it will ignore both "callbackFunctionOK" and "callbackFunctionError".
			successFunction, //callbackFunctionOK. Default: undefined. Ignored if "callbackFunction" is provided.
			errorFunction, //callbackFunctionError. Default: undefined. Ignored if "callbackFunction" is provided.
			[200, 201], //allowedSuccessStatuses. Default: 200.
			null, //asynchronous. Default: true.
			null //XHR. Default: undefined. When not provided, it will try to create a new XHR object internally and it will be returned.
		);
	}
	else
	{
		CB_console("XHR (AJAX) is not supported.");
	}

A way to perform an XHR (AJAX) request for a binary file:


	//Requests a binary file asynchronously:
	var successFunction = function(XHR, callbackFunctionError)
	{
		CB_console("AJAX call succeeded! Status code is: " + CB_Net.XHR.getStatusCode(XHR));
		var contentBytes = new Uint8Array(XHR.response);
		CB_console(contentBytes);
	};
	var errorFunction = function(XHR, callbackFunctionOK)
	{
		CB_console("AJAX call failed! Status code is: " + CB_Net.XHR.getStatusCode(XHR));
	};
	var XHR = CB_Net.XHR.callBinary
	(
		//Parameters ("null" or "undefined" ones will get their default value, if needed, automatically):
		"path_to/my_binary_file.ext", //URL. Unique mandatory parameter.
		null, //data. It can be either a string (like URL parameters) or a JSON object. Default: undefined.
		null, //headers. Default: { "Content-Type" : "text/plain; charset=x-user-defined", "Cache-Control" : "no-cache", "Pragma" : "no-cache" }.
		null, //blobOrArrayBuffer. Default: 'arraybuffer'.
		null, //callbackFunction. Default: undefined. If provided, it will ignore both "callbackFunctionOK" and "callbackFunctionError".
		successFunction, //callbackFunctionOK. Default: undefined. Ignored if "callbackFunction" is provided.
		errorFunction, //callbackFunctionError. Default: undefined. Ignored if "callbackFunction" is provided.
		[200, 201], //allowedSuccessStatuses. Default: 200.
		null //XHR. Default: undefined. When not provided, it will try to create a new XHR object internally and it will be returned.
	);

Sending form data through XHR (AJAX) easily:


	//Performing a common call with form data asynchronously:
	var XHR = CB_Net.XHR.callForm
	(
		"path_to/whatever.ext", //URL. Unique mandatory parameter.
		dataToSend, //data. It can be either a string (like URL parameters) or a JSON object. Default: undefined.
		null, //headers. Default: { "Content-Type" : "application/x-www-form-urlencoded; charset=" + charset, "Cache-Control" : "no-cache", "Pragma" : "no-cache" }.
		null, //responseType. Default: undefined.
		null, //charset. Default: 'UTF-8'.
		null, //callbackFunction. Default: undefined. If provided, it will ignore both "callbackFunctionOK" and "callbackFunctionError".
		successFunction, //callbackFunctionOK. Default: undefined. Ignored if "callbackFunction" is provided.
		errorFunction, //callbackFunctionError. Default: undefined. Ignored if "callbackFunction" is provided.
		[200, 201], //allowedSuccessStatuses. Default: 200.
		null //XHR. Default: undefined. When not provided, it will try to create a new XHR object internally and it will be returned.
	);

It is possible to perform XDR (Cross-domain requests) through a proxy (a default one is already provided by CrossBrowdy):


	//Performing a call through a proxy asynchronously:
	var successFunction = function(XHR, callbackFunctionError)
	{
		CB_console("AJAX call succeeded! Status code is: " + CB_Net.XHR.getStatusCode(XHR));
		CB_console(CB_Net.XHR.getResponseHeaders(XHR)); //Shows the headers received.
		CB_console(CB_Net.XHR.getResponseContent(XHR)); //Shows the content received.
	};
	var errorFunction = function(XHR, callbackFunctionOK)
	{
		CB_console("AJAX call failed! Status code is: " + CB_Net.XHR.getStatusCode(XHR));
	};
	var XHR = CB_Net.XHR.callProxy
	(
		desiredURL, //URL. Unique mandatory parameter. It will be passed to the proxy through the "p_url" parameter.
		null, //method. Default: 'POST'. It will be passed to the proxy through the "p_method" parameter.
		null, //data. It can be either a string (like URL parameters) or a JSON object. Default: undefined. It will be passed to the proxy through the "p_data" parameter.
		null, //headers. Default: undefined. It will be passed to the proxy through the "p_headers" parameter.
		null, //responseType. Default: undefined.
		true, //forceJSON. Default: false. It will be passed to the proxy through the "p_force_json" parameter (with "yes" value).
		true, //getHeaders. Default: false. It will be passed to the proxy through the "p_get_headers" parameter (with "yes" value).
		null, //headersForceOneDimension. Default: false. It will be passed to the proxy through the "p_get_headers_on_dimension" parameter (with "yes" value).
		null, //headersForceOneDimensionValues. Default: false. It will be passed to the proxy through the "p_get_headers_on_dimension_values" parameter (with "yes" value).
		true, //transparentStatus. Default: false. It will be passed to the proxy through the "p_transparent_status" parameter (with "yes" value).
		null, //transparentHeaders. Default: false. It will be passed to the proxy through the "p_transparent_headers" parameter (with "yes" value).
		null, //callbackFunction. Default: undefined. If provided, it will ignore both "callbackFunctionOK" and "callbackFunctionError".
		successFunction, //callbackFunctionOK. Default: undefined. Ignored if "callbackFunction" is provided.
		errorFunction, //callbackFunctionError. Default: undefined. Ignored if "callbackFunction" is provided.
		null, //allowedSuccessStatuses. Default: 200.
		null //XHR. Default: undefined. When not provided, it will try to create a new XHR object internally and it will be returned.
	);

The URL of the proxy used can be defined in the CB_Configuration.CrossBase.CB_Net_XHR_PROXY_URL parameter. By default, it points to a proxy already provided by CrossBrowdy. Read about the CB_Net.XHR.callProxy function to get more information about its usage, the proxy used, how to create your own one if you want, etc.

It is also possible to perform a REST request:


	//Performing a REST call asynchronously:
	var XHR = CB_Net.XHR.callREST
	(
		URL, //serverURL. Default: CB_Net.REST.SERVER_URL_DEFAULT.
		"route/resource/desired", //route. Default: undefined.
		"parameter1=value1&parameter2=value2", //dataURL. It has to be a string (like URL parameters). Default: undefined.
		null, //method. Default: 'POST'.
		{ "parameter3" : "value3", "whatever" : 123 }, //data. It can be either a string (like URL parameters) or a JSON object. Default: undefined.
		null, //headers. Default: undefined.
		null, //responseType. Default: undefined.
		null, //avoidProxy. Default: false. If set to false, it will perform the call through a proxy (using 'CB_Net.XHR.callProxy' internally).
		null, //forceJSON. Default: false. It will be used as the "forceJSON" parameter when calling 'CB_Net.XHR.callProxy' internally (only if "avoidProxy" is false).
		null, //getHeaders. Default: false. It will be used as the "getHeaders" parameter when calling 'CB_Net.XHR.callProxy' internally (only if "avoidProxy" is false).
		null, //headersForceOneDimension. Default: false. It will be used as the "headersForceOneDimension" parameter when calling 'CB_Net.XHR.callProxy' internally (only if "avoidProxy" is false).
		null, //headersForceOneDimensionValues. Default: false. It will be used as the "headersForceOneDimensionValues" parameter when calling 'CB_Net.XHR.callProxy' internally (only if "avoidProxy" is false).
		true, //transparentStatus. Default: false. It will be used as the "transparentStatus" parameter when calling 'CB_Net.XHR.callProxy' internally (only if "avoidProxy" is false).
		null, //transparentHeaders. Default: false. It will be used as the "transparentHeaders" parameter when calling 'CB_Net.XHR.callProxy' internally (only if "avoidProxy" is false).
		successFunction, //callbackFunctionOK. Default: undefined.
		errorFunction, //callbackFunctionError. Default: undefined.
		null, //allowedSuccessStatuses. Default: 200.
		null //XHR. Default: undefined. When not provided, it will try to create a new XHR object internally and it will be returned.
	);

Have into account that it is recommended to use the CB_Net.REST static class instead to perform REST calls easier and in a much more powerful way. To get more information, read the REST topic of the basic tutorial.

Finally, it may also be useful to get a new XHR object:


	//Gets a new XHR object:
	var XHR = CB_Net.XHR.get();

Check the API documentation to read more about the CB_Net and the CB_Net.XHR static classes.

Go back to Guides & Tutorials

« PrevReturnNext »
CrossBrowdy by Joan Alba Maldonado