− Table of content
Jelix supports json-rpc. This is a similar protocol to XML-RPC. The main differences is that data are JSON formatted instead of XML. (RPC = Remote Procedure Call)
Specific entry point ¶
A JSON-RPC request cannot be treated as a classic request, thus you can't use "classic" request object. You have to create a specific entry point in www/
directory, jsonrpc.php
. This entry point should instantiate a jJsonRpcRequest
instead of a jClassicRequest
.
The new entry point should look like:
require_once ('../../myapp/application.init.php');
$config_file = 'jsonrpc/config.ini.php';
require_once (JELIX_LIB_CORE_PATH.'request/jJsonRpcRequest.class.php');
$jelix = new jCoordinator($config_file);
$jelix->process(new jJsonRpcRequest());
Don't forget to add this entry point in urls engine configuration section. If you have selected simple url engine, in section simple_urlengine_entrypoints configuration file, just add:
jsonrpc = "@jsonrpc"
jsonrpc is the entry point name and @jsonrpc is the entry point request type.
If you have selected significant url engine, just add :
<entrypoint type="jsonrpc" name="jsonrpc" default="true" />
Independently of url engines, you retrieve an url for a jsonrpc action like this:
$url = jUrl::get("module~action@jsonrpc");
Controller ¶
As JSON-RPC is a specific request type, a controller filename must be suffixed by ".jsonrpc.php". A "default" controller file would be: "default.jsonrpc.php". (it can co-exists with a "default" classic controller such as "default.classic.php").
Controller content is similar to those of a classic controller. You just have to use a jResponseJsonRpc response (alias:"jsonrpc"):
class defaultCtrl extends jController {
function index(){
$resp = $this->getResponse('jsonrpc');
// any data types : integer, string, array, objects...
$data_php = ... ;
$resp->response = $data_php;
return $resp;
}
}
Client request ¶
To send a jsonrpc request, as specified in json-rpc spec, you have to use a specific json string:
{ method : "",
id:"",
params: {}
}
method parameter indicates which action to execute. In a Jelix application, it must be an action selector:
method:"myModule~default:index"
params parameter datas will be assigned to params member of your response. In your action, you will access them like this:
$parameters = $this->param('params');
Of course, $parameters will contain "php" datas. the JSON string is decoded by jJsonRpcRequest
..
Note: there are javascript methods in lib/jelix-www/js/json.js
. First, toJSONString()
which is added on all javascript object, and which allows to generate a JSON string. Second, javascript strings have a parseJSON method to parse a json string. Then, you just have to pass a string to xmlHttpRequest to send the JSONRPC request to jelix. An HTMl example:
var jsonrpc = { method : "myModule~default:index",
id:"1",
params: null
};
var toSend = jsonrpc.toJSONString();
var p = new XMLHttpRequest();
p.onload = null;
p.open("POST", "http://mysupersite.tld/jsonrpc.php", false);
p.send(toSend);
var response = p.responseText.parseJSON();
var result = reponse.result;
And in your jelix action, if you do:
$resp->response = "hello";
In your javascript example, result variable content will be "hello".