CompleteFTP makes it very easy to call JSS functions as Remote Procedure Calls (RPC). It does this by automatically generating client-side proxies for calling server-side functions, meaning that adding a remotely invocable server-side function is as easy as adding a client-side function.
Functions declared in the global scope and those referenced by the publish function (without the serverOnly flag) are automatically made available via RPC when the URL of the .jss file in which they're defined are referenced by allowed script tag in HTML. The Javascript code required to call them is automatically generated by CompleteFTP (see here).
The following example illustrates some usages:
function globalFunction() {
}
(function () {
function publishedFunction() {
}
function serverOnlyFunction() {
}
function internalFunction() {
}
publish("publishedFunction", publishedFunction);
publish("serverOnlyFunction", serverOnlyFunction, { serverOnly: true });
}());Both globalFunction() and publishedFunction() are available for RPC, the former because it's a global function and the latter because it's published using the publish function. Neither internalFunction() and serverOnlyFunction() are not available via RPC, but serverOnlyFunction() may be called by any other .jss file that includes it using the include function because it's published with the serverSide flag.
Two forms of RPC are supported: JSON-RPC and form-based RPC.
CompleteFTP uses JSON-RPC 2.0 for client-server communications. JSON-RPC is a minimalist JSON-based RPC protocol. For example, the call to the hello() function in the Introduction to JSS is marshalled as
{"jsonrpc": "2.0", "method": "hello", "params": ["world"], "id": 1}which returns the result in the following form:
{"jsonrpc": "2.0", "result": "Hello world from the server", "id": 1}Errors are returned as:
{"jsonrpc": "2.0", "error": {"code": 0, "message": "An error occurred"}, "id": 1}CompleteFTP also supports form-based RPC. A function call must use HTTP POST. If an element named method is included in the form then the Javascript function with that name will be called. The arguments in the call will match the elements in the form - in the same order. Thus the hello() function in the Introduction to JSS may be called by HTTP-POST using the following HTML:
<html>
<body>
<form method=post>
<input type=hidden name=method value=hello>
<input type=text name=firstName>
<input type=submit>
</form>
</body>
</html>Function calls must use HTTP POST. From CompleteFTP 26.1.1 onwards a function invocation (a JSON-RPC call, or a form-RPC request containing a method element) sent by any other method — in particular HTTP GET — is rejected with 405 Method Not Allowed. This closes a cross-site request-forgery vector (a malicious page could otherwise trigger a credentialed GET via an <img>/<script> tag or a top-level navigation) and keeps function parameters out of access logs, browser history and Referer headers. Earlier versions also accepted GET, e.g. script.jss?method=hello&firstName=world; such calls must now be changed to POST.
Plain page requests (a .jss page with no method element, served by processRequest) and client-proxy generation (?proxy) are unaffected and remain available over GET.
The result is returned in the JSON-RPC format, i.e.
{"jsonrpc": "2.0", "result": "Hello world from the server", "id": 1}