DeveloperGuidelines DeveloperGuidelinesTips

== ajaxS3 - the real world connectivity tool ==

When there is too much data to download,
or the connection is slow, 
or the server is busy 
or all of the above,

1. the user would prefer to monitor the browser-server dialogue;
2. the browser would need to re-submit the Ajax request again in the case of timeout.

The [http://bazaar.launchpad.net/~flavour/sahana/sahanapy-trunk/annotate/head%3A/static/scripts/S3/S3.js ajaxS3] covers these needs.
The [http://www.vimeo.com/9526668 demo] is available.

This is a jQuery plugin residing in the S3.js, which works transparently as a regular ajax handle,
but behind the scenes:

1. It shows the flashing message that the download is started
2. It sets up the timeout and re-tries the request several times if the timeout is triggered
3. It displays the status and errors in the custom StatusBar

That way the user always feels and stays in control.


'''How to use the ajaxS3?'''


The standard handles have been provided: ''getS3'', ''getJSONS3'', ''postS3'', and the ''ajaxS3'' itself.[[BR]]


getJSONS3
{{{
$.getJSONS3(url, callback)
$.getJSONS3(url, callback, message)
$.getJSONS3(url, data, callback) 
$.getJSONS3(url, data, callback, message)
}}} 
 These calls will get the JSON from the URL and use the provided callback when successful.
{{{
#!js
callback(theJSON_you_need, status)
}}}
getS3
 It is the same as '''getJSONS3''', but now the type can be 'html' (the type='json' makes it equivalent to getJSONS3):
{{{
#!js
$.getS3(url, callback, type)  
$.getS3(url, callback, type, message)
$.getS3(url, data, callback, type)
$.getS3(url, data, callback, type, message)
}}}
postS3
 The same as '''getS3''', but now the request goes through the POST tunnel:
{{{
#!js
$.postS3(url, callback, type)  
$.postS3(url, callback, type, message)
$.postS3(url, data, callback, type)
$.postS3(url, data, callback, type, message)
}}}

Why the ''message'' argument?[[BR]]
The call `$.getJSONS3(url, callback)` will show status something like:
{{{
"getting form data..."
"getting form data... retry 1"
...
}}}
And the call `$.getJSONS3(url, callback, 'line items')` will show:
{{{
"getting line items..."
"getting line items... retry 1"
...
}}}
DeveloperGuidelines DeveloperGuidelinesTips