Ajax

Ajax(URL[, method[, data[, returnFunction[,failFunction]]]])
Ajax(URL[, returnFunction])
Ajax(URL, settingsObject)

Description

The Ajax function is used to get or receive data from a server. It is based on XMLHttpRequest. This function will only work when running from a server (including the built in AppStudio local server) and is subject to the same-origin policy in some cases. It is a wrapper for jQuery's $.ajax() function. You will need to use a server with PHP enabled: the AppStudio Server does not have PHP enabled.

For much more on using the Ajax function, see Ajax Made Simple.

URL is the address on the server. It can be the name of a file to be downloaded from the server or a script to be run on the server. Optional information can be passed to the server at the end of the URL: for example

 http://www.nsbasic.com/getCustomerInfo.php?customer=Knuth 

will call the PHP script named getCustomerInfo.php, passing the parameter customer=Knuth. Data passed in URLs must be encoded properly. This is done with encodeURIComponent.

Use method to define the access method. If this parameter is omitted, GET is used. The most common value for this is POST. POST responses are never cached, whereas GET responses can be. POST also allows larger data transfers. If you are using POST, put the information you want to send in data. The normal size limit for data is 8 megabytes: it is a server setting which can be increased. This is an easy and efficient way to send data to a server. Other useful methods are DELETE and PUT. For more information on these options, see XMLHttpRequest's open method. For more information on other methods see HTTP request methods.

returnFunction, if supplied, is a function to be called when the results return, allowing asynchronous execution. If this parameter is not supplied, execution will continue at the next statement after the results return. Do not put MsgBox statements inside your Ajax code: they mess up the event sequence.

If you do not use a returnFunction, you will see a warning in the Chrome Debugger:

Synchronous XMLHttpRequest on the main thread is deprecated because of its detrimental effects 
to the end user's experience. For more help, check http://xhr.spec.whatwg.org/.

failFunction, if supplied, is a function to be executed if the Ajax() call fails.

settingsObject is an object containing all the settings, in the form {data: "some data", type: "GET", success: AjaxWorked}. For a complete list of possible settings, see the $.ajax docs.

It returns the following values:

.status:	The status of the response to the request. This is the HTTP result code (for example, status is 200 for a successful request). 404 means page not found.
.statusText:	The response string returned by the HTTP server. Unlike status, this includes the entire text of the response message ("200 OK", for example).
.responseText:	The response to the request as text, or null if the request was unsuccessful or has not yet been sent.
.readyState:	The state of the request: State Description 0 UNSENT:The request is not initialized 1 OPENED: The request has been set up 2 HEADERS_RECEIVED send() has been called, and headers and status are available. 3 LOADING: Downloading; responseText holds partial data. 4 DONE: The request is complete

See also samples Ajax and AjaxPost for more information.

Example (BASIC)

'Ajax example
req = Ajax("/sendData_ajax.php?myText=" & encodeURIComponent(txtSend.value))
If req.status = 200 Then 'success
    txtResponse.value = req.responseText
Else 'failure
    txtResponse.value = "Error: " & req.err.message
End If

'Sample POST call
req = Ajax("/sendData_ajaxPost.php", "POST", "myText=" & encodeURIComponent(txtSend.value))

Example (JavaScript)

//Ajax example
req = Ajax("/sendData_ajax.php?myText=" + encodeURIComponent(txtSend.value));
if(req.status == 200) { //success
    txtResponse.value = req.responseText;
  } else { //failure
    txtResponse.value = "Error: "  +  req.err.message;
}

 //Sample POST call
req = Ajax("/sendData_ajaxPost.php" , "POST" , "myText="  +  encodeURIComponent(txtSend.value));

Related Items

• getJSON

• ReadFile

• Ajax made Simple

• EncodeURIComponent/decodeURIComponent