JavaScript REST Proxy

From Appmethod Topics
Jump to: navigation, search

Go Up to REST

When using the REST Application wizard, a server project will be created that contains several web files. Some of them are simply examples of how to use the JavaScript proxy (ServerFunctionInvoker.html, ReverseString.html, ServerFunctionInvoker.js, connection.js, as well as all of the images and css files). The other files, the JavaScript files, are there for handling all of the XMLHTTPRequest and JSON conversion issues; so that all you need to worry about when writing your client is which server methods to invoke.

To create a new web page, you can follow the example of the other page producer components, or enable the file dispatcher for HTM;HTML dispatching and put your HTML file in the same directory the exe will be published to, or any subdirectory of that. The web page you create will require, at minimum, references to the json-min.js, ServerFunctionExecutor.js and ServerFunctions.js (the proxy) files, but will also require base64.js if you will be using an authentication manager in your server, and CallbackFramework.js if you will be working with heavyweight callbacks.

If you have a server method class called “TServerMethods1” and a public function in that, called “EchoString”, which takes in a string and returns a string, you can invoke this server method remotely from the web page with the following JavaScript code:

var Proxy = new TServerMethods1();
var Response = Proxy.EchoString(“Hello World”);
alert(Response.result); //displays a dialog with message “Hello World”

This creates an instance of the proxy class, which has the same name as the server method class on the server. It then calls the EchoString function on the proxy, which knows how to format the request and use an XMLHTTPRequest behind the scenes to invoke the server’s function. This call returns a JSON Object of key-value pairs, where each key is the name of the parameter as it is in the server code (‘result’ for the return parameter) and each value is the value passed in (for input parameters) or the value returned (for var/out/return parameters.)

The JavaScript proxy (ServerFunctions.js) is generated for you automatically for projects created from the REST Application wizard. This is done by adding a hook into the OnBeforeDispatch event of the file dispatcher, which calls into the proxy generator if the proxy file is seen to be out of date. Inside of the JS proxy you will find a 'class' (function) for each server methods class you have registered on your server, and also one for DSAdmin. In each of these JS classes you will find a function that maps to a server method with the same name and same method signature on the server. If you have this function on the server:

function ReverseString(Value: String): String;

Then you will have this function in the JavaScript proxy:

function ReverseString(Value) ...

Handling the Result

As mentioned before, the result of invoking the JavaScript function is not simply the result returned from the server method. You get a JSON Object back that, if the invocation was successful, will be a key-value pair of each of the parameters and their final values. The result of a Server function call can be accessed from the "result" property of the returned object. Any other parameters of the server function can be accessed with their name, as it appears in the signature of the server method in Object Pascal.

Some parameter names are not supported, specifically any names that would clash with JavaScript keywords like 'arguments'. Also not allowed are: returnObject and resultArray.

If you want the result to be returned asynchronously instead of on the same thread the function was invoked from, pass in a function as an additional parameter after you've set the values for all the parameters listed in the signature of the JavaScript function. Using the EchoString function as an example, that would look something like this:

var HandleResult = function(jsonValue) {
  //handle the result

Proxy.EchoString('Hello World', HandleResult);