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
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.
Some browsers will not let you issue the same Ajax query repeatedly (iOS Home Screen apps, for example - an error 412 is returned). The solution is to add the time to the URL, which will be unique:
http://www.nsbasic.com/getCustomerInfo.php?customer=Knuth?myText=" & encodeURIComponent(Now)
method
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
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
failFunction, if supplied, is a function to be executed if the Ajax() call fails.
settingsObject
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.
returned value
An object is returned which includes 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));