Ajax: Difference between revisions

From NSB App Studio
Jump to navigation Jump to search
No edit summary
No edit summary
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
Ajax(''URL''[, ''method''[, ''data''[, ''returnFunction'']]])<br>
Ajax(''URL''[, ''method''[, ''data''[, ''returnFunction''[,''failFunction'']]]])<br>
Ajax(''URL''[, ''returnFunction''])<br>
Ajax(''URL''[, ''returnFunction''])<br>
Ajax(''URL'', ''settingsObject'')
Ajax(''URL'', ''settingsObject'')
Line 5: Line 5:
== Description ==
== Description ==


The Ajax function is used to get or receive data from a server. It is based on [[:wikipedia:XMLHttpRequest|XMLHttpRequest]]. This function will only work when running from a server (including the built in AppStudio local server) and is subject to the [[wikipedia:Same-origin_policy|same-origin policy]] in some cases. It is a wrapper for [https://api.jquery.com/jQuery.ajax/ jQuery's $.ajax() function]. You will need to use a server with PHP enabled: nsbapp.com site does not have PHP enabled.
The Ajax function is used to get or receive data from a server. It is based on [[:wikipedia:XMLHttpRequest|XMLHttpRequest]]. This function will only work when running from a server (including the built in AppStudio local server) and is subject to the [[wikipedia:Same-origin_policy|same-origin policy]] in some cases. It is a wrapper for [https://api.jquery.com/jQuery.ajax/ jQuery's $.ajax() function]. You will need to use a server with PHP (or other server side scripting) enabled: VoltServer does not have PHP enabled.


For much more on using the Ajax function, see [[Ajax made Simple|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  
''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  
   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/decodeURIComponent|encodeURIComponent]].
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/decodeURIComponent|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 [[:wikipedia:XMLHttpRequest#The_open_method|XMLHttpRequest's open method]].  For more information on other methods see [[:wikipedia:Hypertext_Transfer_Protocol#Request_methods|HTTP request methods]].
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 [[:wikipedia:XMLHttpRequest#The_open_method|XMLHttpRequest's open method]].  For more information on other methods see [[:wikipedia:Hypertext_Transfer_Protocol#Request_methods|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.
''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.


''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 [https://api.jquery.com/jQuery.ajax/ $.ajax docs].
If you do not use a ''returnFunction'', you will see a warning in the [[Using the Chrome Debugger|Chrome Debugger]]:
<pre>
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/.</pre>


It returns the following values:
=== failFunction ===
''failFunction'', if supplied, is a function to be executed if the Ajax() call fails.


.status:  The status of the response to the request. This is the [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP result code] (for example, status is 200 for a successful request). 404 means page not found.
=== 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 [https://api.jquery.com/jQuery.ajax/ $.ajax docs].
.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.
=== returned value ===
An object is returned which includes the following values:


.readyState: The state of the request:
{| class="wikitable"
|-
| .status: || The status of the response to the request. This is the [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes 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:
<pre>
<pre>
State  Description
State  Description
Line 34: Line 54:
4      DONE: The request is complete
4      DONE: The request is complete
</pre>
</pre>
|}


See also samples Ajax and AjaxPost for more information.
See also samples Ajax and AjaxPost for more information.


== Example (BASIC) ==
== Example ==
 
<tabber>
JavaScript=
<syntaxhighlight lang="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;
}


<pre>
//Sample POST call
req = Ajax("/sendData_ajaxPost.php" , "POST" , "myText="  +  encodeURIComponent(txtSend.value));
 
</syntaxhighlight>
|-|
BASIC=
<syntaxhighlight lang="vb.net">
'Ajax example
'Ajax example
req = Ajax("/sendData_ajax.php?myText=" & encodeURIComponent(txtSend.value))
req = Ajax("/sendData_ajax.php?myText=" & encodeURIComponent(txtSend.value))
Line 50: Line 88:
'Sample POST call
'Sample POST call
req = Ajax("/sendData_ajaxPost.php", "POST", "myText=" & encodeURIComponent(txtSend.value))
req = Ajax("/sendData_ajaxPost.php", "POST", "myText=" & encodeURIComponent(txtSend.value))
</pre>
== Example (JavaScript) ==


<pre>
</syntaxhighlight>
//Ajax example
</tabber>
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));
</pre>


== Related Items ==
== Related Items ==

Latest revision as of 15:39, 25 February 2021

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 (or other server side scripting) enabled: VoltServer 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

//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));

'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))

Related Items