Nano Ajax Library

Setup

Simply include the .js file in the web page:

Functions

gid(id)

Shorthand for document.getElementById(id);
example:

<div id="example1_container">click the button to change text</div>
<button onclick="gid('example1_container').innerHTML='Hello';">
Change Text
</button>

sample:

click the button to change text

hb()

internally used to generate a timestamp (heartbeat) to prevent unwanted caching

ajxb(url, post_data)

Makes a synchronous (blocking) XMLHttpRequest (XHR) call and returns the server response

example:

<div id="example2_container">click the button to change text</div>
<button onclick="alert(ajxb('docs/servertime.php?delay=5'));">
Server Time
</button>

sample:

click the button to get server time

Note a delay is added to the server response to highlight the asynchronocy behavior.

ajxnb(xhr_object, url, callback_function, post_data)

Mostly used by ajxpgn to send and handle asynchronous XHR calls
example:

<div id="example3_container">click the button to get server time</div>
<button onclick="example3_click();">Server Time</button>
<script>
function example3_click(){
gid('example3_container').innerHTML='loading...';
var xhr_object=xmlHTTPRequestObject();
ajxnb(xhr_object,'docs/servertime.php?delay=2',example3_callback(xhr_object));
}

function example3_callback(xhr_object){return function(){
if (xhr_object.readyState==4)
gid('example3_container').innerHTML=xhr_object.responseText;
}}
</script>

sample:

click the button to get server time

ajxpgn(container, url, force_display, eval_scripts, post_data, callback, si_limit, once)

One of the most used functions in nano.js
It loads the response of an XHR server response to a specified container

a trivial example:

<div id="example4_container">click the button to get server time</div>
<button
onclick="ajxpgn('example4_container','docs/servertime.php?delay=2')">
Server Time
</button>

try it:

click the button to get server time

When force_display is set to true (false by default), even a hidden container becomes visible. In practice, this parameter is seldom used, as the show/hide part is often defined explicitly in callbacks.

eval_scripts is set to false by default. its use should be deprecated.

A quick way to remember the first 4 parameters is "CUDE" - Container, URL, Display and Eval.

Following CUDE is the POST data payload. Use encodeHTML to encode each query component.

The callback function comes in two forms: a simple callback, or an array of success and error functions.

ajxpgn('container','services.php',0,0,null,function(){alert("I'm back!");});

click the button to get server time

An error function can be passed as a callback to handle server-side exceptions:

ajxpgn('container','error.php?',0,0,null,[function(){},function(s,m,rq){alert("bad / "+s+" / "+m);}]);

click the button to try your luck

In the above example, a server-side script generates a random number between 0 and 100. If the generated number is less than 50, an error is thrown.

A server-side application error is signaled by the "apperror" header. In Gyroscope the apperror function performs effectively the following:

header('apperror: '.rawurlencode('your error message here')); die();

ajxpgn passes three parameters to the error callback. An "errfunc" selector, and the error message itself. The errfunc allows the server to influence how the error is handled on the client side. The last parameter is the XHR object "rq". Additional header information may be transmitted via the XHR object.

If no error handling function is specified, ajxpgn displays the error in a simple alert:

ajxpgn('container','error.php?');

click the button to get a simple error

When the above button gives an error, the errfunc is indeed set. Except that the function is not declared. We can load "myerrfunc" dynamically:

ajxjs(self.myerrfunc,'errfunc.js?');

Click on the Load button, and then the Check button in the previous example.

The server specified client-side function is only called when there is no explicit error handler in the callback parameter. Only the server-side message is passed to this "simple" error handler. In most cases this is sufficient. If more dynamic client-side routing is needed, pass the callback functions as an array.

ajxpgn('container','error.php?',0,0,null,[function(){},function(s,m){alert('A: '+m);}]);
ajxpgn('container','error.php?',0,0,null,[function(){},function(s,m){alert('B: '+m);}]);

try different buttons

In practice, error callbacks can be used to forward a resume function during a flow interrupt such as an AJAX sign-on overlay. The behavior of what happens after a successful sign-in is defined before invoking the action. Error callback is available starting v3.2.

The si_limit parameter has no effect; it holds a parameter position so that the ajxpgn call is consistent in both public and Gyroscope versions. In Gyroscope, the slow-indicator defaults to 800ms, meaning if the server doesn't respond within 800ms, a wait-indicator animation starts to play.

ajxpgn displays the response to the most recent request (in-order delivery) by discarding in-flight XHR requests. this behavior may be changed with the once flag.

ajxjs(function_identifier,javascript_filename)

Loads javascript functions on-demand

The following snippet will load a sayhi.js only once when clicking on the Load button.
Then you can type in javascript:sayhi();void(0); in the browser address to verify that it is dynamically loaded.

Note the JavaScript function has to be functional variables:

sayhi=function(){...} //works
function sayhi(){...} //doesn't work

ajxcss(singleton_identifier,css_filename)

Dynamically loads and applies CSS file

Clicking on the Load button will change the look of all the buttons on this page:

xajx(url)

Makes a cross-domain request without refreshing the current page

Note this experimental function does not XHR. It sends data to the server-side script using the url string, and executes the returned JavaScript code asynchronously.

xmlHTTPRequestObject()

Returns an XHR object. See ajxnb for sample use.

Windows 8 Metro App

Although the Windows 8 Metro App is a different run-time environment from a standard web browser, nano.js can still be used after the following patch:

Locate the following line in the ajxpgn function:

ct.innerHTML=rq.responseText;

Then wrap around the code with the following lines:

MSApp.execUnsafeLocalFunction(function() {
ct.innerHTML=rq.responseText;
})

If you manually alter the innerHTML content, for example when using ajxb, use the above treatment to allow script injection.