responsejsonrpc.gtw

~~LANG:EN@enman:responsejsonrpc~~

Jelix propose la prise en charge du protocole [[http://json-rpc.org/|json-rpc]].
Ce protocole d'échange est similaire à XML-RPC dans le fonctionnement, mais
utilise JSON comme format de donnée au lieu de XML (RPC = Remote Procedure
Call).

===== Point d'entrée spécifique =====

Une requête JSON-RPC est spécifique, et pour y répondre, on ne peut pas utiliser
[[requests|l'objet request]] "classic". Il vous faut créer un point d'entrée
spécifique dans le répertoire @@F@www/@@, @@F@jsonrpc.php@@ par exemple, qui
utilise @@C@jJsonRpcRequest@@ plutôt que @@C@jClassicRequest@@. Le type de
requête et du point d'entrée est donc "jsonrpc".

Le point d'entrée devra contenir ceci :

<code php>
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());

</code>

Il ne faut oublier de déclarer ce point d'entrée au niveau de la configuration
des moteurs d'urls simple ou significant. Si vous utilisez
[[/urls/simple|le moteur d'url simple]], vous devez mettre dans la section
//simple_urlengine_entrypoints// de la configuration de jelix la déclaration
suivante : 

<code ini>
jsonrpc = "@jsonrpc"
</code>

//jsonrpc// étant le nom du point d'entrée, et //@jsonrpc// indiquant le type de point d'entrée.

Si vous utilisez [[urls/significant|le moteur d'url significant]], vous devez ajouter la balise suivante :
<code xml>
<entrypoint type="jsonrpc" name="jsonrpc" default="true" />
</code>

Dans un cas comme dans l'autre, vous pouvez alors récupérer l'url d'une action
pour jsonrpc comme ceci :

<code php>
  $url = jUrl::get("module~action@jsonrpc");
</code>

===== Contrôleur =====

Comme on a affaire à un type de requête particulier, le nom du fichier du
contrôleur doit avoir le suffixe ".jsonrpc.php". Par exemple, un contrôleur
"default" : "default.jsonrpc.php". (Vous pouvez bien sûr avoir un autre
contrôleur "default" pour d'autres types de requêtes, "default.classic.php" par
exemple).

Ensuite, le contenu du contrôleur est similaire à ce que vous avez l'habitude de
faire, à la seule différence que vous utiliserez jResponseJsonRpc, qui a pour
alias "jsonrpc", pour répondre aux requêtes JsonRpc :

<code php>
class defaultCtrl extends jController {

  function index(){

    $rep = $this->getResponse('jsonrpc');

    // n'importe quelles types de données : entier, chaine, array, objets...
    $donnees_php = ... ;

    $rep->response = $donnees_php;

    return $rep;

  }
}
</code>


===== Appel depuis le client =====

Qui dit JsonRpc, dit une partie cliente qui envoie une requête jsonrpc. Comme
vous pouvez le lire dans [[http://json-rpc.org/|la spécification de jsonrpc]],
il faut envoyer une chaîne de ce type :

<code>
{ method : "",
  id:"",
  params: {}
}
</code>

Dans method, vous indiquerez, dans le cas d'un appel à une application jelix, le
sélecteur de l'action à appeler :

<code>
method:"monModule~default:index"
</code>

Les données que vous mettrez dans params seront mises dans le paramètre "params"
dans la réponse. Ainsi, pour les récupérer dans l'action vous ferez :

<code php>
  $parametres = $this->param('params');
</code>

Bien entendu, ce que vous avez dans $parametres sera des données "php" (chaine,
array ou autre), la transformation de la chaine json étant réalisée par
@@C@jJsonRpcRequest@@..

Notez qu'un script javascript est fourni dans @@F@lib/jelix-www/js/json.js@@. Il
vous permet, dans vos pages HTML de transformer vos données javascript en chaine
json. Pour cela, sur les objets, tableaux et autre type de donnée javascript, il
suffit d'appeler la méthode javascript @@M@toJSONString()@@ qui renvoie une
chaîne. Il suffit ensuite de passer cette chaîne à xmlHttpRequest pour envoyer
la requête JSONRPC à jelix. Exemple, dans votre page HTML :

<code javascript>
 var jsonrpc = { method : "monModule~default:index",
    id:"1",
    params: null
 };

 var toSend = jsonrpc.toJSONString();
 var p = new XMLHttpRequest();
 p.onload = null;
 p.open("POST", "http://monsite.tld/jsonrpc.php", false);
 p.send(toSend);

 var reponse = p.responseText.parseJSON();
 var resultat = reponse.result;
</code>

Enfin si dans l'action jelix, vous avez fait un 

<code php>
  $rep->response = "hello";
</code>

Vous aurez alors dans la variable //resultat// de l'exemple javascript, une chaîne "hello".