Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.
Sencha Integration: Ext Direct
Diligence makes it trivial to support Ext Direct, Sencha's straightforward RPC protocol. Ext Direct it has excellent support in Ext JS and Sencha Touch: the frameworks generate a client-side namespace for you with asynchronous methods equivalent to those on the server. All you have to do is call them! Operations are batched for maximum efficiency, and errors are handled as elegantly as can be.
Diligence actually takes Ext Direct one step ahead in letting you automatically generate the API configuration on the server. A "GET" to the resource will retrieve the JSON needed to configure the client-side provider. We show this in detail under "Usage," below.
Ext Direct's functionality is practically identical to that JSON-RPC, but the protocol is incompatible. It may be unfortunate that Sencha decided not to use that better-known protocol, but in any case Diligence supports both.
Setup
Make sure to check out the server-side API documentation for Diligence.Sencha and Diligence.RPC, as well as the client-side API documentation for Ext Direct.
Ext Direct setup is almost identical to RPC Service setup, so make sure you read the section there.
One small difference is in how Ext Direct handles namespaces. First of all, you cannot have an empty namespace (the "." namespace in JSON-RPC). And, second, you can optionally set up a client-side namespace, using the "name" key. Here's an example "/libraries/resources.js", similar to the one for the RPC Service:
document.executeOnce('/diligence/integration/frontend/sencha/')
var Calc = {
multiply: function(x, y) {
return x y
}
}
resources = {
...
calc: new Diligence.Sencha.DirectResource({name: 'MyApp', namespaces: {Calc: Calc}})
}
It is also possible to set Ext Direct method attributes using the long-form method definition with the "extDirect" key.
Ext JS Forms
Ext Direct can be used to respond to Ext JS form submissions. To do so, we need to set the "formHandler" attribute and also return an appropriate response:
var Calc = {
multiply: {
fn: function(x, y) {
return {
success: true,
msg: '{0} times {1} is {2}'.cast(x, y, x y)
}
},
extDirect: {
formHandler: true
}
}
}
See the section on Ext JS Forms for more information on usage. Note furthermore that Diligence supports all of Ext JS's form submission mechanisms.
Usage
See the Ext JS documentation for full details on the client-side API. Otherwise, here's a quick tutorial, which also shows you how to fetch the provider configuration from the resource.
Here's an example of a dynamic web page, say "direct.d.html":
<html>
<head>
<%
document.executeOnce('/diligence/integration/frontend/sencha/')
Diligence.Sencha.extJsHead(conversation)
%>
</head>
<body>
</body>
<script>
function init() {
MyApp.Calc.multiply(2, 3, function(provider, response) {
if (response.type == 'exception') {
Ext.Msg.alert('Multiplication', 'Exception: ' + response.message);
}
else {
Ext.Msg.alert('Multiplication', response.result);
}
});
}
Ext.Ajax.request({
url: '<%= conversation.pathToBase %>/calc/',
method: 'GET',
disableCaching: false,
success: function(response) {
var provider = Ext.decode(response.responseText);
Ext.Direct.addProvider(provider);
init();
},
failure: function(response) {
console.log(response);
}
});
</script>
</html>
Some notes:
- Make sure you understand the difference between the server-side JavaScript (between the "<%" and "%>" delimiters) and the client-side JavaScript (between the "<script>" and "</script>" delimiters)!
-
We are using "Ext.Ajax.request" to do a "GET" on our resource. It will return the JSON needed for the call to "Ext.Direct.addProvider". Here's how it would look in our example:You can avoid that "Ext.Ajax.request" call by simply copying and pasting that JSON into your client-side source code. This extra call is simply a convenience allowing you to modify the server-side code without worrying about also having to update the client-side code accordingly. You might prefer to keep this extra call during development, and then freeze it for production code.
{ "actions": { "Calc": [{ "name": "multiply", "len": 2 }] }, "namespace": "MyApp" } - We are disabling the default "disableCaching" mode in "Ext.Ajax.request". Ext JS disabled caching by default in order to better deal with servers that do not handle REST properly. Since Prudence does this for us, there's no reason to avoid client-side caching if it's possible.
- The last argument for any Ext Direct method is a callback that is called when the server returns a response. It's cumbersome, but that's the price you pay for asynchronous remote calls! Also note that you want to properly handle server and network failures.
The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.
