svn commit: r1607030 - /thrift/cms-site/trunk/content/tutorial/js.md

[he...@apache.org]

Author: henrique
Date: Tue Jul  1 10:15:25 2014
New Revision: 1607030

URL: http://svn.apache.org/r1607030
Log:

jQuery tutorial

Modified:
    thrift/cms-site/trunk/content/tutorial/js.md

Modified: thrift/cms-site/trunk/content/tutorial/js.md
URL: http://svn.apache.org/viewvc/thrift/cms-site/trunk/content/tutorial/js.md?rev=1607030&r1=1607029&r2=1607030&view=diff
==============================================================================
--- thrift/cms-site/trunk/content/tutorial/js.md (original)
+++ thrift/cms-site/trunk/content/tutorial/js.md Tue Jul  1 10:15:25 2014
@@ -6,7 +6,7 @@ library_lang: "js"
 
 ### Prerequisites 
 
-* This tutorial depends on an existing Thrift server. See either the [Java tutorial](/tutorial/java) or [C++ tutorial](/tutorial/cpp) for how to build and setup one of these servers.
+* This tutorial depends on an existing Thrift server. See either the [Java tutorial](/tutorial/java) or [node.js tutorial](/tutorial/nodejs) for how to build and setup one of these servers.
 
 ### Client
 
@@ -99,11 +99,31 @@ and
 		CalculatorClient.prototype.calculate = function(logid, w) {}
 		
 Unfortunately, the Javascript object isn't just called Calculator and there are a lot of other functions defined as well, but how those are used are out of the scope of this tutorial.  
-	
+
 ### Inspecting the Thrift.js file
 
-* The Thrift.js library currently uses jQuery.js in it's usage.
 * The main goal of the library is to define the Transport and Protocol layers.
-* The Transport layer only uses AJAX as of right now.  
-* The Protocol layer handles the encoding/decoding to JSON format.
+* The Transport layer can use AJAX or WebSockets.  
+* The Protocol layer handles the encoding/decoding to JSON or Binary format.
 * There are also the Thrift object types and call functions defined here as well.
+* The Thrift.js library can use jQuery.js if provided.
+
+#### jQuery API
+
+jQuery aware JS source files can generated using the *jq* compiler option:
+
+    thrift --gen js:jq tutorial.thrift
+
+This does not change the default behavior of the library, i.e. service calls will be done synchronously. However, services will start using jQuery.ajax when a callback function is provided as showed below.
+
+    client.calculate(1, work, function(result) { alert(result); });
+
+This method call will return immediately but the callback function (and its *alert*) will be called as soon as a response is received from the server. The service call also returns a jqXHR object, which has more callback options:
+
+    client.calculate(1, work, function(){} )
+    .fail( function(jqXHR, status, error) {  alert(error.message); } )
+    .done( function(result) { /* success! do something */ } )
+    .always( function() { /* do something more */ } );
+
+For more information refer to: http://api.jquery.com/jquery.ajax/
+Note: Synchronously calls are easy to debug and good for testing but should not be used on a front-end browser, as it will normally result on the a whole browser freeze until the response is back.