Quick links: Content - sections - sub sections
EN FR

Jelix supports json-rpc. This is a similar protocol to XML-RPC. The main differences is that datas are JSON formatted instead of XML.

RPC = Remote Procedure Call

See Xml-rpc documentation.

Specifi 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 will instantiate a jJsonRpcRequest instead of a jClassicRequest.

The new entry point should look like:


require_once ('../../lib/jelix/init.php');
require_once ('../../MYAPPLI/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 :


<jsonrpcentrypoint 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/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".